# PerfectPay API

API de integração para produtores e afiliados: consulta de vendas, assinaturas, tracking e invoice.

**Autenticação**

Todas as requisições usam o header `Authorization: Bearer <token>`. São aceitos dois tipos de token:

- **Token de integração** — gerado no painel em *Ferramentas > API*.
- **Token pessoal** — obtido via `POST /api/auth/login`.

**PostBack (webhook de saída)**

Veja a seção *Webhooks* no menu para o payload e os eventos do webhook enviado à sua URL cadastrada.

**Integração com IA (llms.txt)**

Esta API expõe arquivos em texto plano seguindo o padrão [llms.txt](https://llmstxt.org) — uma convenção para publicar documentação em markdown limpo, otimizado para leitura por modelos de linguagem e agentes.

- [/llms.txt](app.perfectpay.com.br/llms.txt) — índice curado e leve: visão geral, autenticação e a lista dos 7 endpoints com links. Bom como contexto inicial de um agente ou ponto de entrada para navegação sob demanda.
- [/llms-full.txt](app.perfectpay.com.br/llms-full.txt) — versão expandida gerada do OpenAPI, com parâmetros e respostas de cada endpoint inline. Use quando a IA precisar do contexto completo em uma única leitura, como em RAG ou geração de código de integração.
- [/docs/api.json](app.perfectpay.com.br/docs/api.json) — OpenAPI 3.1 canônico e machine-readable, para gerar clients/SDKs, importar em ferramentas ou alimentar pipelines automatizados.

Na prática: comece pelo [/llms.txt](app.perfectpay.com.br/llms.txt) para orientar o agente, recorra ao [/llms-full.txt](app.perfectpay.com.br/llms-full.txt) quando precisar dos detalhes de cada rota e use o [/docs/api.json](app.perfectpay.com.br/docs/api.json) para tooling e geração de SDK.

## Endpoints

### POST /api/auth/login — Login (token pessoal)

Autentica com e-mail e senha e retorna um `access_token` (token pessoal, scope `personal_access`, validade ~1 mês).
Use o token no header `Authorization: Bearer <access_token>` nas demais chamadas.

Body:
- `email` (string, obrigatório) — E-mail da conta PerfectPay.
- `password` (string, obrigatório) — Senha da conta.

Respostas:
- 400
- 403
- 200
- 401
- 429: An error
- 422

### POST /api/v1/sales/get — Buscar vendas

Lista vendas do produtor com filtros por data (venda/aprovação/atualização), status, código do produto,
e-mail do comprador ou código da transação.

**Variante afiliação premium:** quando o token pertence a uma afiliação premium, cada item de `sales.data` vem em formato reduzido — apenas `transaction_token`, `sale_status`, `payment_type`, `date_created`, `date_approved`, `currency_enum`, `currency_enum_key` e `commissions` (neste caso um objeto `{value, affiliation_type}`, e não a lista de comissões do produtor).

Body:
- `page` (integer|null, opcional) — Página da paginação (1 a 10000).
- `paginate` (integer|null, opcional) — Itens por página (1 a 1000).
- `start_date_approved` (string, opcional) — Data inicial de aprovação da venda, no formato yyyy-mm-dd.
- `end_date_approved` (string, opcional) — Data final de aprovação da venda, no formato yyyy-mm-dd. Obrigatório junto com start_date_approved.
- `start_date_sale` (string, opcional) — Data inicial da venda (criação), no formato yyyy-mm-dd.
- `end_date_sale` (string, opcional) — Data final da venda (criação), no formato yyyy-mm-dd. Obrigatório junto com start_date_sale.
- `start_date_updated` (string, opcional) — Data inicial de atualização da venda, no formato yyyy-mm-dd.
- `end_date_updated` (string, opcional) — Data final de atualização da venda, no formato yyyy-mm-dd. Obrigatório junto com start_date_updated.
- `sale_status` (array|null, opcional) — Filtra por status da venda (array de valores de SaleStatusEnum).
- `transaction_token` (string|null, opcional) — Código da transação da venda.
- `email` (string|null, opcional) — Filtro por e-mail do comprador.
- `product_code` (string|null, opcional) — Filtra por código do produto (aceita múltiplos códigos separados por vírgula).

Respostas:
- 400
- 200
- 403
- 401
- 422

### POST /api/v1/tracking/create — Criar tracking

Registra o código e URL de rastreio de uma venda, identificada pelo transaction_token.

Body:
- `transaction_token` (string, obrigatório) — Código da transação da venda (obrigatório).
- `tracking_code` (string, obrigatório) — Código de rastreio gerado pela transportadora.
- `tracking_url` (string, obrigatório) — URL de rastreio da transportadora.
- `external_id` (string, opcional) — Identificador externo do envio (opcional).
- `status_tracking` (string, obrigatório) — Status do envio (ex.: Enviado, Entregue).

Respostas:
- 400
- 422
- 401
- 200

### POST /api/v1/tracking/get — Buscar tracking

Consulta o rastreio de envio de uma venda, identificada pelo transaction_token.

Body:
- `transaction_token` (string, obrigatório) — Código da transação da venda (obrigatório).

Respostas:
- 400
- 401
- 200
- 422

### POST /api/v1/invoice/create — Criar invoice (nota fiscal)

Registra a nota fiscal (invoice) de uma venda, identificada pelo transaction_token.

Body:
- `transaction_token` (string, obrigatório) — Código da transação da venda (obrigatório).
- `external_id` (string|null, opcional) — Identificador externo da nota fiscal (opcional).
- `logistic_id` (string|null, opcional) — Identificador do envio/logística vinculado (opcional).
- `fiscal_number` (string, obrigatório) — Número da nota fiscal.
- `fiscal_access_key` (string, obrigatório) — Chave de acesso da nota fiscal.
- `fiscal_pdf` (string, obrigatório) — URL do PDF da nota fiscal.
- `fiscal_xml` (string|null, opcional) — URL do XML da nota fiscal (opcional).
- `fiscal_status` (string, obrigatório) — Status da nota fiscal.
- `fiscal_date_emission` (string, obrigatório) — Data/hora de emissão da nota fiscal, no formato yyyy-mm-dd HH:ii:ss.

Respostas:
- 400
- 401
- 200
- 422

### POST /api/v1/invoice/get — Buscar invoice

Lista as notas fiscais (invoices) do produtor, com filtro opcional por transaction_token e período.

Body:
- `transaction_token` (string|null, opcional) — Filtra pela transação da venda (opcional).
- `start_date` (string|null, opcional) — Data inicial do período de emissão, no formato yyyy-mm-dd. Padrão: ontem.
- `end_date` (string|null, opcional) — Data final do período de emissão, no formato yyyy-mm-dd. Padrão: hoje.
- `page` (number|null, opcional) — Página da paginação.

Respostas:
- 400
- 401
- 200
- 422

### POST /api/v1/subscriptions/get — Buscar assinaturas

Lista assinaturas do produtor com filtros por status, e-mail ou CPF/CNPJ do cliente.
A resposta inclui currency_enum, subscription_amount_float e o detalhamento de status
(subscription_status_enum, subscription_status_detail, subscription_detail_enum).

Body:
- `subscription_status_enum` (integer, opcional) — Filtro de status da assinatura (1-7, ver SubscriptionStatusEnum). Valores: 1 = trial, 2 = active (ativa), 3 = cancelled (cancelada), 4 = awaiting_payment (aguardando pagamento), 5 = expired (expirada), 6 = in_mediation (em disputa), 7 = finished (finalizada).
- `recurrent_type_enum` (integer, opcional) — Filtro de tipo de recorrência (1-7, ver RecurrentTypeEnum). Observação: atualmente este filtro não é aplicado na busca (no-op) — os resultados não são filtrados por tipo de recorrência. Valores: 1 = 7 dias, 2 = 15 dias, 3 = mensal, 4 = trimestral, 5 = semestral, 6 = anual, 7 = vitalício.
- `customer_email` (string, opcional) — Filtro por e-mail do cliente.
- `identification_number` (string, opcional) — Filtro por CPF/CNPJ do cliente.
- `page` (integer, opcional) — Página da paginação.

Respostas:
- 400
- 200
- 401