API Reference
Referência técnica completa dos endpoints da API Conta Simples
Sobre esta seção
A API Reference é a referência técnica dos endpoints da API Conta Simples. Aqui você encontra:
- Todos os endpoints disponíveis com parâmetros e schemas
- Exemplos de request e response
- Códigos de resposta HTTP
- Playground interativo para testar chamadas
Novo por aqui? Recomendamos começar pelos Guides antes de explorar a referência técnica. Os guias explicam os conceitos e fluxos — esta seção foca nos detalhes técnicos de cada endpoint.
Como usar esta referência
Entenda o fluxo nos Guides
Leia o Fluxo de Integração Recomendado para entender a jornada completa.
Consulte o endpoint específico
Use esta referência para ver parâmetros, tipos e exemplos de cada endpoint.
Teste no playground
Use o playground interativo ao lado de cada endpoint para testar chamadas diretamente.
Consulte o Dicionário de Dados
Para entender o significado de cada campo, consulte o Dicionário de Dados.
Endpoints disponíveis
POST /oauth/v1/access-token
Obtém um token de acesso (JWT) via OAuth 2.0 Client Credentials para autenticar nas chamadas à API.
GET /statements/v1/credit-card
Consulta extrato de transações de cartão por período. Retorna transações com dados de cartão, categoria, centro de custo e anexos.
PATCH /statements/v1/credit-card/{transactionId}
Atualiza uma transação de cartão. Campos editáveis: notes (string, máximo 1000 caracteres), isConciled (boolean) e categoryId (integer). Use o id (ULID) retornado no GET do extrato. Envie string vazia para limpar notes.
GET /attachments/v1/content/{attachmentId}
Download do conteúdo binário de um anexo (comprovante, nota fiscal, recibo) em PNG, JPEG ou PDF.
Autenticação
Todas as requisições requerem autenticação via Bearer token no header Authorization:
curl -X GET https://api-sandbox.contasimples.com/statements/v1/credit-card \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-H "User-Agent: {nome-do-seu-app}/{versao}"
| Header | Valor | Obrigatório |
|---|---|---|
Authorization | Bearer {TOKEN} | Sim |
Content-Type | application/json | Sim (para POST) |
Guia de Autenticação
Como obter e renovar tokens de acesso.
Notas por endpoint
POST /oauth/v1/access-token
Primeiro acesso? Veja o Guia de Autenticação para entender o fluxo completo de OAuth 2.0 Client Credentials, boas práticas de renovação e segurança de credenciais.
GET /statements/v1/credit-card
Contexto: Para entender o significado dos campos retornados, consulte o Dicionário de Dados. Para padrões de paginação e retry, veja Boas Práticas.
PATCH /statements/v1/credit-card/{transactionId}
Contexto: O transactionId é o campo id (ULID) da transação no extrato (GET /statements/v1/credit-card). O PATCH aceita os campos notes (string, máximo 1000 caracteres — envie "" para limpar), isConciled (boolean — marca a transação como conciliada (true) ou não conciliada (false)) e categoryId (integer — ID retornado por GET /categories/v1/categories). Ao menos um campo deve ser informado. Resposta 204 No Content em caso de sucesso.
curl -X PATCH https://api-sandbox.contasimples.com/statements/v1/credit-card/01JB4M8WQ2YX5KN7RT9HF3DE6C \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{"notes":"Almoço com cliente Acme","isConciled":true,"categoryId":1146}'
GET /attachments/v1/content/{attachmentId}
Contexto: Os IDs dos anexos são retornados no array attachments de cada transação (GET /statements/v1/credit-card). Para exemplos de download, veja Boas Práticas — Anexos.
Convenções
Datas
| Contexto | Formato | Exemplo |
|---|---|---|
| Parâmetros de entrada | YYYY-MM-DD | 2025-01-15 |
| Campos de resposta | ISO 8601 | 2025-01-15T14:30:00.000Z |
Valores monetários
Valores vêm como number (decimais) em Reais (BRL).
Paginação
Paginação baseada em cursor via nextPageStartKey. Veja Boas Práticas — Paginação para implementação completa.