API Pública Noctra

Visão Geral

A API pública do Noctra está disponível em https://api.noctra.org/v1. A versão atual é v1 e todos os endpoints são read-only.

Quickstart

1. Crie uma API key em Dashboard → API & Webhooks.
2. Envie requisições com o header Authorization: Bearer <NOCTRA_API_KEY>.
3. Comece por GET /v1/projects.

curl --request GET \
  --url https://api.noctra.org/v1/projects \
  --header "Authorization: Bearer noctra_live_xxx"

Autenticação

Use API keys geradas no dashboard do Noctra. As chaves podem ser escopadas, revogadas e são exibidas apenas uma vez na criação.

Authorization: Bearer <NOCTRA_API_KEY>

Rate Limits

Rate limits são aplicados por API key. As respostas incluem:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Erros

Todos os erros seguem um envelope consistente.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid pagination params. Use numeric `page` and `per_page`.",
    "request_id": "a8d2fdb3-67f8-4de6-aa30-13c2abca1f6f"
  }
}

Paginação

Endpoints de listagem suportam page e per_page. Os metadados de paginação são retornados em pagination.

Projects

Endpoints: GET /v1/projects, GET /v1/projects/{project_id}

Visits

Endpoints: GET /v1/visits, GET /v1/visits/{visit_id}

Clicks

Endpoints: GET /v1/clicks, GET /v1/clicks/{click_id}

Checkouts

Endpoints: GET /v1/checkouts, GET /v1/checkouts/{checkout_id}

Sales

Endpoints: GET /v1/sales, GET /v1/sales/{sale_id}

Refunds

Endpoints: GET /v1/refunds, GET /v1/refunds/{refund_id}

Upsells

Endpoints: GET /v1/upsells, GET /v1/upsells/{upsell_id}

Webhooks

Eventos suportados: checkout.started, sale.created, refund.created, upsell.created.

{
  "id": "evt_9f4de8dd",
  "type": "sale.created",
  "created_at": "2026-03-10T11:23:45Z",
  "data": {
    "id": "sale_2f6e4a",
    "project_id": "8bfbdffe-3fa6-4dd4-b796-745b7f0e59ea",
    "status": "approved",
    "amount": "99.00",
    "currency": "USD"
  }
}

Assinaturas de Webhook

O Noctra assina o raw body da requisição usando HMAC SHA-256. Use:

• X-Noctra-Event
• X-Noctra-Delivery
• X-Noctra-Signature with format sha256=<hex>

Teste de Webhooks

Use a ação Enviar teste no painel API & Webhooks para enfileirar um evento realista de teste sale.created.

Changelog

2026-03-10: Primeira versão da API pública v1 e gestão de webhooks.