# API Conta Simples

## Português

- [API Conta Simples](https://developers.contasimples.com/br/index.md): Portal de desenvolvedores para integração com a Conta Simples
- [Quickstart](https://developers.contasimples.com/br/comece-aqui/quickstart.md): Configure seu ambiente e faça sua primeira chamada à API em 5 minutos
- [Autenticação](https://developers.contasimples.com/br/comece-aqui/autenticacao.md): Como autenticar suas requisições de forma segura com OAuth 2.0
- [Ambientes](https://developers.contasimples.com/br/comece-aqui/ambientes.md): Entenda os ambientes Sandbox e Produção, o limite de requisições e como acessar suas credenciais
- [Fluxo de Integração Recomendado](https://developers.contasimples.com/br/guias/fluxo-integracao.md): Passo a passo completo para integrar com a API Conta Simples
- [Boas Práticas](https://developers.contasimples.com/br/guias/boas-praticas.md): Padrões recomendados para paginação, tratamento de erros, retry e mais
- [Dicionário de Dados](https://developers.contasimples.com/br/referencia/dicionario-dados.md): Descrição detalhada de todas as entidades, campos e enumerações da API
- [Erros Comuns](https://developers.contasimples.com/br/operacao/erros-comuns.md): Diagnóstico e resolução dos erros mais frequentes
- [Suporte & Contato](https://developers.contasimples.com/br/operacao/suporte.md): Canais de atendimento da Conta Simples
- [API Reference](https://developers.contasimples.com/br/api-reference/introducao.md): Referência técnica completa dos endpoints da API Conta Simples
- [Download de Anexo](https://developers.contasimples.com/br/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
- [Obter Token de Acesso](https://developers.contasimples.com/br/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 **30 minutos** (`expires_in: 1800`).
- 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://developers.contasimples.com/br/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://developers.contasimples.com/br/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://developers.contasimples.com/br/api-reference/post-credit-cards-v1-id-unblock.md): Desbloqueia um cartão corporativo previamente bloqueado pelo ID.
- [Listar Categorias](https://developers.contasimples.com/br/api-reference/get-categories-v1-categories.md): Retorna as categorias disponíveis para a empresa. Cada item pode incluir estabelecimentos vinculados e metadados de tipo (por exemplo, categoria personalizada ou padrão).
- [Criar Categoria](https://developers.contasimples.com/br/api-reference/post-categories-v1-categories.md): Cria uma nova categoria personalizada para a empresa autenticada. O nome deve ser único entre as categorias da empresa. O contexto da empresa é obtido a partir do token de acesso.
- [Obter Categoria por ID](https://developers.contasimples.com/br/api-reference/get-categories-v1-categories-id.md): Retorna os dados de uma categoria da empresa pelo identificador numérico, incluindo estabelecimentos vinculados e metadados de tipo. O escopo é sempre a empresa associada ao token.
- [Listar Centros de Custo](https://developers.contasimples.com/br/api-reference/get-cost-centers-v1-cost-centers.md): Use este endpoint para listar todos os centros de custo disponíveis para a empresa autenticada. O contexto da empresa é obtido automaticamente a partir do token de acesso.

O uso mais comum é obter o `id` de um centro de custo para classificar transações via `PATCH /statements/v1/credit-card/{transactionId}`.

**Regras:**
- Retorna todos os centros de custo da empresa, sem paginação.
- O campo `responsible` é opcional; quando ausente, o centro de custo não possui responsável vinculado.
- [Listar Fornecedores](https://developers.contasimples.com/br/api-reference/get-suppliers-v1-suppliers.md): Liste todos os fornecedores da empresa. Use os IDs retornados para classificar despesas ao criar ou editar transações. Retorna todos os fornecedores cadastrados. Não há paginação.
- [Criar Fornecedor](https://developers.contasimples.com/br/api-reference/post-suppliers-v1-suppliers.md): Cria um novo fornecedor para a empresa autenticada.

**Regras:**
- O campo `name` é obrigatório e não pode ser vazio.
- Não é possível criar dois fornecedores com o mesmo nome para a mesma empresa.

Depois de criar o fornecedor, use o ID retornado para classificar despesas ao registrar transações.
- [Consultar Fornecedor por ID](https://developers.contasimples.com/br/api-reference/get-suppliers-v1-suppliers-id.md): Retorna os dados de um fornecedor específico da empresa pelo ID numérico.

**Regras:**
- O `id` é o campo `id` retornado em [GET /suppliers/v1/suppliers](/br/api-reference/get-suppliers-v1-suppliers).
- Retorna 404 se o fornecedor não for encontrado.
- [Extrato Bancário](https://developers.contasimples.com/br/api-reference/get-statements-v1-banking.md): Consulta o extrato de transações bancárias da empresa com suporte a filtros e paginação por cursor.

**Regras:**
- `startDate` é obrigatório quando `endDate` é informado e vice-versa.
- O `limit` deve estar entre **1** e **50** itens por página (padrão: 20).
- Use `nextPageStartKey` para navegar entre páginas (paginação por cursor).
- Os filtros de valor (`amountEq`, `amountGt`, `amountLt`) são mutuamente exclusivos.
- [Extrato de Cartão](https://developers.contasimples.com/br/api-reference/get-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).
- [Atualizar Transação de Cartão](https://developers.contasimples.com/br/api-reference/patch-statements-v1-credit-card-transactionid.md): Atualiza informações editáveis de uma transação de cartão de crédito, identificada por `transactionId`.

Use este endpoint para enriquecer despesas no seu fluxo de conciliação ou ERP — por exemplo, registrar contexto da compra, conciliar a transação ou classificá-la por categoria.

**Campos editáveis hoje:**
- `notes` — observação da transação (máximo **1000** caracteres). Envie string vazia (`""`) para limpar.
- `isConciled` — marca a transação como conciliada (`true`) ou desconciliada (`false`).
- `categoryId` — ID numérico da categoria.
- `costCenterId` — UUID do centro de custo (use o valor do campo `id` retornado em [GET /cost-centers/v1/cost-centers](/br/api-reference/get-cost-centers-v1-cost-centers)).

**Regras:**
- O `transactionId` deve ser o **`id`** da transação retornado no extrato (`GET /statements/v1/credit-card`) — **ULID** (ex.: `01JB4M8WQ2YX5KN7RT9HF3DE6C`); não é UUID.
- Ao menos um campo deve ser informado no corpo.
- Em caso de sucesso, a API retorna **204 No Content** (sem corpo).
- [Listar Convites](https://developers.contasimples.com/br/api-reference/get-users-v1-invites.md): Retorna a lista paginada de convites de usuários da empresa, com filtros opcionais por status e papel (role).

Use `nextPageStartKey` para navegar entre páginas (paginação por cursor).
- [Criar Convite](https://developers.contasimples.com/br/api-reference/post-users-v1-invites.md): Envia um convite para um novo usuário se juntar à empresa. O convite é enviado para o e-mail informado com o papel (role) especificado.

**Regras:**
- O `roleId` deve ser um UUID v4 válido de um papel existente na empresa.
- O `email` deve ser um endereço de e-mail válido.
- Não é possível enviar convite para um e-mail que já possui convite pendente ou que já está vinculado à empresa.
- [Listar Papéis (Roles)](https://developers.contasimples.com/br/api-reference/get-users-v1-roles.md): Retorna a lista de papéis (roles) da empresa, incluindo permissões associadas a cada papel.

Cada papel contém informações como nome, perfil, descrição, quantidade de usuários vinculados e os grupos de permissões (claims) atribuídos.
- [Listar Usuários](https://developers.contasimples.com/br/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).
- [Consultar Usuário por ID](https://developers.contasimples.com/br/api-reference/get-users-v1-users-userid.md): Retorna os dados de um usuário específico da empresa pelo `userId`. Use este endpoint quando você já conhece o identificador do usuário e quer consultar ou atualizar o contexto de um único usuário sem paginar a listagem completa.

**Regras:**
- O `userId` é o campo `id` retornado por [GET /users/v1/users](/br/api-reference/get-users-v1-users).
- Retorna 404 se o usuário não pertencer à empresa autenticada.
- [Atualizar Usuário](https://developers.contasimples.com/br/api-reference/patch-users-v1-users-userid.md): Atualiza parcialmente os dados de um usuário da empresa. Apenas os campos enviados são alterados; campos omitidos permanecem inalterados.

**Regras:**
- `name` e `roleId` só podem ser alterados em usuários ativos.
- Não é possível alterar o e-mail do usuário.
- Não é possível alterar um usuário com perfil principal (MAIN).
- Não é possível rebaixar o único administrador (RESPONSIBLE) da conta.
- Retorna 404 se o usuário não pertencer à empresa autenticada.
- [Excluir Usuário](https://developers.contasimples.com/br/api-reference/delete-users-v1-users-userid.md): Remove um usuário da empresa pelo ID.

**Regras:**
- O `userId` deve ser um UUID v4 válido de um usuário existente na empresa.
- Não é possível excluir o usuário com perfil principal (MAIN).
- [Model Context Protocol (MCP)](https://developers.contasimples.com/br/mcp/index.md): Conecte agentes e assistentes de IA à plataforma Conta Simples por meio de servidores MCP
- [Developer MCP](https://developers.contasimples.com/br/mcp/developer-mcp.md): Assistente com IA para desenvolvedores que integram a API Conta Simples
- [Conta Simples MCP](https://developers.contasimples.com/br/mcp/conta-simples-mcp.md): Permita que agentes de IA executem operações reais na plataforma Conta Simples
- [Changelog](https://developers.contasimples.com/br/operacao/changelog.md): Histórico de mudanças da API Conta Simples
- [Convenções do Changelog](https://developers.contasimples.com/br/operacao/como-funciona-changelog.md): Convenções, versionamento e política de breaking changes da API Conta Simples

## English

- [Conta Simples API](https://developers.contasimples.com/en/index.md): Developer portal for integrating with Conta Simples
- [Quickstart](https://developers.contasimples.com/en/comece-aqui/quickstart.md): Set up your environment and make your first API call in 5 minutes
- [Authentication](https://developers.contasimples.com/en/comece-aqui/autenticacao.md): Authenticate your requests securely with OAuth 2.0
- [Environments](https://developers.contasimples.com/en/comece-aqui/ambientes.md): Understand Sandbox and Production, request limits, and how to access your credentials
- [Recommended integration flow](https://developers.contasimples.com/en/guias/fluxo-integracao.md): Step-by-step guide to integrate with the Conta Simples API
- [Best practices](https://developers.contasimples.com/en/guias/boas-praticas.md): Recommended patterns for pagination, error handling, retries, and more
- [Data dictionary](https://developers.contasimples.com/en/referencia/dicionario-dados.md): Detailed description of entities, fields, and enumerations in the API
- [Common errors](https://developers.contasimples.com/en/operacao/erros-comuns.md): Diagnose and fix the most frequent errors
- [Support & contact](https://developers.contasimples.com/en/operacao/suporte.md): Conta Simples support channels
- [API Reference](https://developers.contasimples.com/en/api-reference/introducao.md): Full technical reference for the Conta Simples API endpoints
- [Download attachment](https://developers.contasimples.com/en/api-reference/get-attachments-v1-content-attachmentid.md): Downloads the binary content of a transaction attachment. Attachment IDs are returned in each transaction’s `attachments` array in the card statement response.

**Supported formats:**
- `image/png` — screenshots, photos
- `image/jpeg` — photos, scanned receipts
- `application/pdf` — invoices, documents
- [Get access token](https://developers.contasimples.com/en/api-reference/post-oauth-v1-access-token.md): Returns a JWT access token using OAuth 2.0 Client Credentials. Send **api_key** and **api_secret** in the `Authorization: Basic` header as the base64-encoded string `api_key:api_secret`.

Credentials are managed in [Conta Simples Internet Banking](https://ib.contasimples.com/integracoes/api/credenciais).

**Important:**
- The token expires in **30 minutes** (`expires_in: 1800`).
- Refresh the token **before** it expires to avoid interruptions.
- Use `Content-Type: application/x-www-form-urlencoded` in the body (only `grant_type=client_credentials`).
- [List cards](https://developers.contasimples.com/en/api-reference/get-credit-cards-v1-cards.md): Returns a paginated list of the company’s corporate cards, with optional filters for status, type, cardholder email, product name, and last 4 digits.

**Available filters:**
- `status`: ACTIVATED, BLOCKED, CANCELLED, INACTIVATED
- `type`: PHYSICAL, VIRTUAL
- `email`: cardholder email
- `productName`: card product name
- `last4`: last 4 digits of the card number

Use `nextPageStartKey` to page through results (cursor-based pagination).
- [Block card](https://developers.contasimples.com/en/api-reference/post-credit-cards-v1-id-block.md): Blocks a corporate card by ID. You may include an optional block reason in the request body.

**Note:** a blocked card can be unblocked later with the unblock endpoint.
- [Unblock card](https://developers.contasimples.com/en/api-reference/post-credit-cards-v1-id-unblock.md): Unblocks a previously blocked corporate card by ID.
- [List categories](https://developers.contasimples.com/en/api-reference/get-categories-v1-categories.md): Returns categories available to the company. Each item may include linked establishments and type metadata (e.g. custom or default).
- [Create category](https://developers.contasimples.com/en/api-reference/post-categories-v1-categories.md): Creates a new custom category for the authenticated company. The name must be unique among the company’s categories. Company context is taken from the access token.
- [Get category by ID](https://developers.contasimples.com/en/api-reference/get-categories-v1-categories-id.md): Returns a company category by numeric ID, including linked establishments and type metadata. Scope is always the company associated with the token.
- [List cost centers](https://developers.contasimples.com/en/api-reference/get-cost-centers-v1-cost-centers.md): Use this endpoint to list all cost centers available for the authenticated company. The company context is automatically obtained from the access token.

The most common use is to retrieve the cost center `id` to classify transactions via `PATCH /statements/v1/credit-card/{transactionId}`.

**Rules:**
- Returns all cost centers for the company, without pagination.
- The `responsible` field is optional; when absent, the cost center has no assigned owner.
- [List Suppliers](https://developers.contasimples.com/en/api-reference/get-suppliers-v1-suppliers.md): List all suppliers for your company. Use the returned IDs to classify expenses when creating or editing transactions. Returns all registered suppliers. No pagination.
- [Create Supplier](https://developers.contasimples.com/en/api-reference/post-suppliers-v1-suppliers.md): Creates a new supplier for the authenticated company.

**Rules:**
- The `name` field is required and must not be empty.
- Two suppliers with the same name cannot exist for the same company.

Once created, use the returned supplier ID to classify expenses when recording transactions.
- [Get Supplier by ID](https://developers.contasimples.com/en/api-reference/get-suppliers-v1-suppliers-id.md): Returns the data for a specific company supplier by numeric ID.

**Rules:**
- The `id` is the `id` field returned by [GET /suppliers/v1/suppliers](/en/api-reference/get-suppliers-v1-suppliers).
- Returns 404 if the supplier is not found.
- [Banking statement](https://developers.contasimples.com/en/api-reference/get-statements-v1-banking.md): Returns the company’s banking statement with optional filters and cursor-based pagination.

**Rules:**
- If you pass `endDate`, you must pass `startDate`, and vice versa.
- `limit` must be between **1** and **50** per page (default: 20).
- Use `nextPageStartKey` to paginate.
- The amount filters (`amountEq`, `amountGt`, `amountLt`) are mutually exclusive.
- [Card statement](https://developers.contasimples.com/en/api-reference/get-statements-v1-credit-card.md): Returns card transactions for a date range. The response is paginated and includes card, category, cost center, status, and attachments.

**Rules:**
- The range between `startDate` and `endDate` must not exceed **62 days**.
- `limit` must be between **5** and **100** per page.
- Use `nextPageStartKey` to paginate (cursor).
- [Update Card Transaction](https://developers.contasimples.com/en/api-reference/patch-statements-v1-credit-card-transactionid.md): Updates editable fields on a credit card transaction, identified by `transactionId`.

Use this endpoint to enrich expenses in your reconciliation flow or ERP — for example, by recording purchase context, reconciling the transaction, or classifying it by category.

**Editable fields today:**
- `notes` — transaction notes (max **1000** characters). Send an empty string (`""`) to clear.
- `isConciled` — marks the transaction as reconciled (`true`) or unreconciled (`false`).
- `categoryId` — numeric category ID.
- `costCenterId` — UUID of the cost center (use the `id` field from [GET /cost-centers/v1/cost-centers](/en/api-reference/get-cost-centers-v1-cost-centers)).

**Rules:**
- `transactionId` must be the transaction **`id`** from the statement (`GET /statements/v1/credit-card`) — a **ULID** (e.g. `01JB4M8WQ2YX5KN7RT9HF3DE6C`), not a UUID.
- At least one field must be provided in the body.
- On success, the API returns **204 No Content** (no body).
- [List invites](https://developers.contasimples.com/en/api-reference/get-users-v1-invites.md): Returns a paginated list of user invites, with optional filters for status and role.

Use `nextPageStartKey` to paginate.
- [Create invite](https://developers.contasimples.com/en/api-reference/post-users-v1-invites.md): Sends an invite for a new user to join the company. The message goes to the given email with the selected role.

**Rules:**
- `roleId` must be a v4 UUID for a role in the company.
- `email` must be valid.
- You cannot invite an address that already has a pending invite or is already a member.
- [List roles](https://developers.contasimples.com/en/api-reference/get-users-v1-roles.md): Returns the company’s roles, including permissions for each role.

Each role includes a name, profile, description, linked user count, and claim groups.
- [List users](https://developers.contasimples.com/en/api-reference/get-users-v1-users.md): Returns a paginated list of company users, with an optional email filter.

Use `nextPageStartKey` to paginate.
- [Get User by ID](https://developers.contasimples.com/en/api-reference/get-users-v1-users-userid.md): Returns details for a specific company user by their `userId`. Use this endpoint when you already know the user's identifier and want to look up or refresh a single user without paginating through the full list.

**Rules:**
- The `userId` is the `id` field from [GET /users/v1/users](/en/api-reference/get-users-v1-users).
- Returns 404 if the user does not belong to the authenticated company.
- [Update User](https://developers.contasimples.com/en/api-reference/patch-users-v1-users-userid.md): Partially updates a user's data for the authenticated company. Only the fields included in the request body are updated; omitted fields remain unchanged.

**Rules:**
- `name` and `roleId` can only be updated for active users.
- The user's email cannot be changed.
- Users with the MAIN profile cannot be updated.
- The last administrator (RESPONSIBLE) of the account cannot be demoted.
- Returns 404 if the user does not belong to the authenticated company.
- [Delete user](https://developers.contasimples.com/en/api-reference/delete-users-v1-users-userid.md): Removes a user from the company by ID.

**Rules:**
- `userId` must be a valid v4 UUID for a user in the company.
- The primary (MAIN) user cannot be deleted.
- [Model Context Protocol (MCP)](https://developers.contasimples.com/mcp/index.md): Connect AI agents and assistants to the Conta Simples platform through MCP servers
- [Developer MCP](https://developers.contasimples.com/mcp/developer-mcp.md): AI-powered assistant for developers integrating with the Conta Simples API
- [Conta Simples MCP](https://developers.contasimples.com/mcp/conta-simples-mcp.md): Enable AI agents to perform real operations on the Conta Simples platform
- [Changelog](https://developers.contasimples.com/en/operacao/changelog.md): Conta Simples API change history
- [Changelog conventions](https://developers.contasimples.com/en/operacao/como-funciona-changelog.md): Conventions, versioning, and breaking change policy for the Conta Simples API