# API Conta Simples

## Guides

- [API Conta Simples](https://conta-simples-1773411870430330332.documentationai.com/index.md): Portal de desenvolvedores para integração com a Conta Simples
- [Quickstart](https://conta-simples-1773411870430330332.documentationai.com/comece-aqui/quickstart.md): Configure seu ambiente e faça sua primeira chamada à API em 5 minutos
- [Autenticação](https://conta-simples-1773411870430330332.documentationai.com/comece-aqui/autenticacao.md): Como autenticar suas requisições de forma segura com OAuth 2.0
- [Ambientes](https://conta-simples-1773411870430330332.documentationai.com/comece-aqui/ambientes.md): Entenda os ambientes Sandbox e Produção e como acessar suas credenciais
- [Fluxo de Integração Recomendado](https://conta-simples-1773411870430330332.documentationai.com/guias/fluxo-integracao.md): Passo a passo completo para integrar com a API Conta Simples
- [Boas Práticas](https://conta-simples-1773411870430330332.documentationai.com/guias/boas-praticas.md): Padrões recomendados para paginação, tratamento de erros, retry e mais
- [Dicionário de Dados](https://conta-simples-1773411870430330332.documentationai.com/referencia/dicionario-dados.md): Descrição detalhada de todas as entidades, campos e enumerações da API
- [Erros Comuns](https://conta-simples-1773411870430330332.documentationai.com/operacao/erros-comuns.md): Diagnóstico e resolução dos erros mais frequentes
- [Suporte & Contato](https://conta-simples-1773411870430330332.documentationai.com/operacao/suporte.md): Canais de atendimento da Conta Simples

## API Reference

- [API Reference](https://conta-simples-1773411870430330332.documentationai.com/api-reference/introducao.md): Referência técnica completa dos endpoints da API Conta Simples
- [Obter Token de Acesso](https://conta-simples-1773411870430330332.documentationai.com/api-reference/post-oauth-v1-access-token.md): Obtém um token de acesso (JWT) via OAuth 2.0 Client Credentials. As credenciais **api_key** e **api_secret** devem ser enviadas no header `Authorization: Basic`, com o valor em base64 da string `api_key:api_secret`.

As credenciais são gerenciadas pelo [Internet Banking da Conta Simples](https://ib.contasimples.com/integracoes/api/credenciais).

**Importante:**
- O token expira em **1 hora** (`expires_in: 3600`).
- Renove o token **antes** da expiração para evitar interrupções.
- Use `Content-Type: application/x-www-form-urlencoded` no body (apenas `grant_type=client_credentials`).
- [Listar Cartões](https://conta-simples-1773411870430330332.documentationai.com/api-reference/get-credit-cards-v1-cards.md): Retorna a lista paginada de cartões corporativos da empresa, com filtros opcionais por status, tipo, e-mail do responsável, nome do produto e últimos 4 dígitos.

**Filtros disponíveis:**
- `status`: ACTIVATED, BLOCKED, CANCELLED, INACTIVATED
- `type`: PHYSICAL, VIRTUAL
- `email`: e-mail do responsável pelo cartão
- `productName`: nome do produto do cartão
- `last4`: últimos 4 dígitos do número do cartão

Use `nextPageStartKey` para navegar entre páginas (paginação por cursor).
- [Bloquear Cartão](https://conta-simples-1773411870430330332.documentationai.com/api-reference/post-credit-cards-v1-id-block.md): Bloqueia um cartão corporativo pelo ID. Opcionalmente, informe o motivo do bloqueio no corpo da requisição.

**Importante:** um cartão bloqueado pode ser desbloqueado posteriormente via endpoint de desbloqueio.
- [Desbloquear Cartão](https://conta-simples-1773411870430330332.documentationai.com/api-reference/post-credit-cards-v1-id-unblock.md): Desbloqueia um cartão corporativo previamente bloqueado pelo ID.
- [Extrato de Cartão](https://conta-simples-1773411870430330332.documentationai.com/api-reference/post-statements-v1-credit-card.md): Consulta o extrato de transações de cartão por período. Retorna uma lista paginada de transações com dados do cartão, categoria, centro de custo, status e anexos.

**Regras:**
- O período entre `startDate` e `endDate` não pode exceder **62 dias**.
- O `limit` deve estar entre **5** e **100** itens por página.
- Use `nextPageStartKey` para navegar entre páginas (paginação por cursor).
- [Download de Anexo](https://conta-simples-1773411870430330332.documentationai.com/api-reference/get-attachments-v1-content-attachmentid.md): Faz o download do conteúdo binário de um anexo vinculado a uma transação. Os IDs dos anexos são retornados no array `attachments` de cada transação no endpoint de extrato.

**Formatos suportados:**
- `image/png` — Screenshots, fotos
- `image/jpeg` — Fotos, recibos escaneados
- `application/pdf` — Notas fiscais, documentos
- [Listar Usuários](https://conta-simples-1773411870430330332.documentationai.com/api-reference/get-users-v1-users.md): Retorna a lista paginada de usuários da empresa, com filtro opcional por e-mail.

Use `nextPageStartKey` para navegar entre páginas (paginação por cursor).

## Collections

- [Collections](https://conta-simples-1773411870430330332.documentationai.com/collections/index.md): Baixe a Postman Collection e o Environment da API Conta Simples para testar os endpoints rapidamente.

## Changelog

- [Changelog](https://conta-simples-1773411870430330332.documentationai.com/operacao/changelog.md): Histórico de mudanças da API Conta Simples
- [Convenções do Changelog](https://conta-simples-1773411870430330332.documentationai.com/operacao/como-funciona-changelog.md): Convenções, versionamento e política de breaking changes da API Conta Simples