Convenções

Estrutura de URLs

A maior parte dos endpoints é escopada por uma conta de vendedor. Os padrões de caminho são:

Padrão	Significado
`/<modulo>/seller/{seller_id}/<recurso>/`	Recursos pertencentes à conta do vendedor. `seller_id` é o UUID da conta unificada.
`/unified/accounts/sellers/{sellers_pk}/<recurso>/`	Mesma ideia, mas roteada pelo módulo unificado.
`/<modulo>/<recurso>/` (sem `seller_id`)	Endpoints administrativos ou públicos.

Quando o caminho tem seller_id, apenas usuários com acesso àquela conta (ou superusuários) podem interagir com ele.

Métodos HTTP

A API segue verbos REST padrão:

Verbo	Para que serve
`GET` (lista)	Lista uma coleção. Suporta paginação.
`GET` (detalhe)	Recupera um recurso.
`POST`	Cria um recurso.
`PATCH`	Atualização parcial.
`PUT`	Atualização total. Poucos endpoints usam — prefira `PATCH`.
`DELETE`	Remove um recurso.

Paginação

Os endpoints de listagem retornam respostas no formato:

{
  "count": 124,
  "next": "https://api.dlpay.cloud/unified/accounts/sellers/.../transactions/?page=2",
  "previous": null,
  "results": [ /* ... */ ]
}

Parâmetros de query:

page — número da página, começando em 1.
page_size — quantidade de itens por página (a API impõe um teto).

Filtros e busca

A maioria dos endpoints aceita parâmetros de query mapeados para campos do recurso. Os mais comuns:

search — busca textual sobre os campos pesquisáveis configurados para o endpoint.
ordering — nome do campo para ordenação. Prefixe com - para descendente.
<campo> — filtro de igualdade direto sobre o campo (quando exposto).

Os campos filtráveis estão listados na referência de cada endpoint.

Filtros por data

A maioria dos endpoints de métricas aceita start_date e end_date no formato YYYY-MM-DD. As datas são interpretadas em America/Sao_Paulo por padrão.

Formato de erro

Os erros seguem um formato consistente. Em linhas gerais:

{
  "detail": "Credenciais de autenticação não foram fornecidas."
}

Para erros de validação:

{
  "nome_do_campo": ["Este campo é obrigatório."],
  "outro_campo": ["Valor inválido."]
}

Códigos de status comuns:

Código	Significado
`200`	OK. Sucesso para GETs e a maior parte de PATCH/PUT.
`201`	Criado. Sucesso padrão para POSTs.
`204`	Sem conteúdo. Usado após DELETE e em algumas operações de credenciais.
`400`	Requisição inválida. Validação falhou.
`401`	Não autenticado. Cabeçalho `Authorization` ausente ou inválido.
`403`	Não autorizado. Autenticado, porém sem permissão.
`404`	Não encontrado, ou você não tem acesso ao recurso.
`409`	Conflito. Criação duplicada ou transição de estado inválida.
`500`	Erro interno. Registrado no monitoramento.

Dinheiro e valores

Todos os valores monetários estão em centavos inteiros de BRL (real brasileiro), salvo indicação explícita em contrário. 1000 representa R$ 10,00.

Identificadores

A maioria dos recursos usa UUIDs (32 caracteres, sem hífens). Alguns recursos voltados ao público usam slugs ou códigos curtos — sinalizamos isso nas páginas correspondentes.

Fuso horário

O fuso da plataforma é America/Sao_Paulo. Todos os datetimes retornados são ISO 8601 com fuso. Ao enviar timestamps, prefira incluir o offset explicitamente (...-03:00).

Primeiros passos

Conceitos

Fluxos

Estrutura de URLs

Métodos HTTP

Paginação

Filtros e busca

Filtros por data

Formato de erro

Dinheiro e valores

Identificadores

Fuso horário

​Estrutura de URLs

​Métodos HTTP

​Paginação

​Filtros e busca

​Filtros por data

​Formato de erro

​Dinheiro e valores

​Identificadores

​Fuso horário

Estrutura de URLs

Métodos HTTP

Paginação

Filtros e busca

Filtros por data

Formato de erro

Dinheiro e valores

Identificadores

Fuso horário