Formato das respostas

Todas as respostas são JSON (application/json). Os endpoints de conteúdo seguem um envelope único de sucesso — { success, data, meta? } — e um envelope único de erro. A exceção são os endpoints de Anúncios (Delivery), que atendem um contrato legado sem envelope.

Envelope de sucesso

Toda resposta 2xx dos endpoints de conteúdo (posts, categorias, tags e busca) tem o mesmo formato:

{
  "success": true,
  "data": {
    "id": "clxxx101",
    "title": "Meu Primeiro Post",
    "slug": "meu-primeiro-post",
    "status": "PUBLISHED"
  }
}

{
  "success": true,
  "data": [
    { "id": "clxxx101", "title": "Primeiro post", "slug": "primeiro-post", "status": "PUBLISHED" },
    { "id": "clxxx102", "title": "Segundo post", "slug": "segundo-post", "status": "PUBLISHED" }
  ]
}

{
  "success": true,
  "data": [ /* … objetos Post … */ ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 143,
      "totalPages": 15,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
}

Exceção: Anúncios (Delivery)

Os endpoints de Anúncios · Delivery atendem um contrato legado/externo e não usam o envelope: a entrega por formato retorna o objeto AdDeliveryResult diretamente, e a entrega em lote retorna um array de AdDeliverySlotResult no nível raiz.

Paginação canônica

Listagens paginadas por page/pageSize retornam os itens em data (array) e os metadados em meta.pagination, no formato canônico PaginationMetaCanonical: page, pageSize, total, totalPages, hasNextPage e hasPrevPage. Detalhes e exemplos de laços em Paginação.

Envelope de erro

Respostas 4xx/5xx vêm com success: false e um objeto error estruturado, com código estável (error.code), indicação de retry (error.retryable) e o identificador da requisição (error.requestId):

{
  "success": false,
  "error": {
    "message": "Post não encontrado",
    "code": "NOT_FOUND",
    "type": "not_found",
    "statusCode": 404,
    "timestamp": "2026-07-01T18:58:22.562Z",
    "retryable": false,
    "path": "/public/posts/abc123",
    "requestId": "req_5c26469a-1234-4c8b-9e21-370450bbda3a",
    "docs": "https://docs.draftin.io/errors/NOT_FOUND"
  }
}

A referência completa de campos, códigos e a estratégia de tratamento estão em Tratamento de erros.

Headers relevantes

Tipos e convenções

Charset e codificação

• Respostas são UTF-8. Acentuação e emojis são preservados.
• O campo content dos posts pode conter HTML ou Markdown, conforme produzido no editor — trate-o de acordo ao renderizar.