API de Integração

Passo a passo

A integração tem duas partes. A preparação é feita uma única vez, por uma pessoa, no navegador: é ali que o escritório prova quem é (CAPTCHA, e-mail confirmado, aceite dos termos) e decide o que o sistema externo poderá fazer. Depois disso, todo o trabalho do dia a dia roda pela API, sem navegador.

Parte 1 — Preparação no navegador (uma vez só)

1. Crie a conta do escritório

   Em Criar conta, informe o CNPJ do escritório (os dados da Receita são preenchidos sozinhos), os dados do administrador e aceite os termos. Esse usuário é o administrador do escritório. Esta é a única etapa com CAPTCHA, e por isso ela não tem equivalente na API.

2. Confirme o e-mail

   Clique no link enviado ao e-mail do administrador. Até confirmar, o escritório pode ter no máximo 3 entidades. O link pode ser reenviado pelo próprio sistema.

3. Cadastre as empresas (opcional nesta etapa)

   Em Minhas entidades → Adicionar entidade, informe o CNPJ. Empresas privadas ficam disponíveis na hora. Órgãos públicos (prefeitura, câmara, fundo, autarquia) ficam aguardando aprovação até a conferência do suporte e só recebem folha depois dela. Você também pode pular este passo e deixar a integração cadastrar as empresas pela API (passo 8).

4. Crie um membro só para a integração

   Em Equipe do escritório → Adicionar membro, cadastre um usuário dedicado (ex.: integracao-erp) com o papel OPERADOR_FOLHA (envia e corrige folha) ou CONSULTA (só leitura). Evite ADMINISTRADOR: com ele, a integração poderia gerenciar a equipe e as próprias credenciais.

   Se a integração deve atuar só em algumas empresas da carteira, clique no acesso do membro (coluna Acesso) e escolha Somente as selecionadas. Veja Perfis e acesso às empresas.

   Confirme também o e-mail desse membro se a integração for cadastrar empresas: membro sem e-mail confirmado não cadastra entidades depois que o escritório atinge o limite de 3 (erro EMAIL_NAO_VERIFICADO). Depois do passo 6, peça o e-mail de confirmação com o token do membro e clique no link recebido na caixa dele:

   curl -X POST https://app.simplesinformatica.com.br/cco/api/escritorio/reenviar-verificacao \
     -H "Authorization: Bearer $TOKEN"

5. Gere a credencial

   Com o administrador, abra Integrações → Nova credencial e escolha o membro do passo anterior. Você recebe um client_id e um client_secret. Copie o segredo na hora: ele não é exibido de novo. Guarde-o como uma senha, fora do código-fonte. Se ele vazar, revogue a credencial na mesma tela e gere outra.

   Na mesma janela você pode limitar a credencial a algumas empresas do membro (Somente as selecionadas). O escopo pode ser alterado depois, pela coluna Entidades, sem trocar o segredo.

Parte 2 — Operação pela API (sem navegador)

6. Obtenha um token

   Troque a credencial por um token de acesso. Ele vale pelo tempo informado em expires_in (segundos). Quando expirar, peça outro da mesma forma: não há refresh token. A resposta também mostra a entidade ativa e o escritório do membro.

   curl -X POST https://app.simplesinformatica.com.br/cco/api/auth/token \
     -H "Content-Type: application/json" \
     -d '{"grant_type":"client_credentials","client_id":"cco_...","client_secret":"cco_sk_..."}'

   {
     "access_token": "eyJhbGciOiJSUzI1NiIs...",
     "token_type": "Bearer",
     "expires_in": 14400,
     "entidade_ativa": { "id": "0190...", "nome": "EMPRESA EXEMPLO LTDA", "papel": "OPERADOR_FOLHA", ... },
     "escritorio": { "id": "0190...", "nome": "ESCRITÓRIO EXEMPLO", ... }
   }

   Em todas as outras chamadas, envie Authorization: Bearer <access_token>.

7. Analise o arquivo antes de enviar

   A análise não grava nada: lê o CNPJ e a competência do arquivo e diz, no campo acao, o que fazer em seguida (veja a tabela abaixo).

   curl -X POST https://app.simplesinformatica.com.br/cco/api/cc/analisar \
     -H "Authorization: Bearer $TOKEN" \
     -F "arquivo=@CC_202608_11222333000181_00001.xml" -F "origem=xml"

8. Se a empresa ainda não existe, cadastre-a

   Quando a análise responde acao: "criar", a empresa do arquivo ainda não está no sistema. Envie o mesmo arquivo para cadastrá-la a partir do CNPJ. A resposta 201 significa que já pode enviar a folha. A resposta 202 significa que é um órgão público aguardando o suporte. Também é possível cadastrar só pelo CNPJ, em POST /entidades.

   curl -X POST https://app.simplesinformatica.com.br/cco/api/cc/criar-entidade-do-arquivo \
     -H "Authorization: Bearer $TOKEN" \
     -F "arquivo=@CC_202608_11222333000181_00001.xml" -F "origem=xml"

9. Envie a folha

   Informe em entidade_id o entidade.id devolvido pela análise. Assim o envio não depende de qual empresa está ativa no token.

   curl -X POST https://app.simplesinformatica.com.br/cco/api/cc/upload \
     -H "Authorization: Bearer $TOKEN" \
     -F "arquivo=@CC_202608_11222333000181_00001.xml" -F "origem=xml" \
     -F "entidade_id=0190..."

10. Consulte e gerencie, em qualquer empresa, com o mesmo token

    As rotas de folha, trabalhadores, senhas e dados de contracheque aceitam entidade_id: na query em GET/DELETE e no corpo em POST/PUT. Sem ele, vale a entidade ativa do token. A lista das empresas que o token alcança está em GET /entidades/minhas — já filtrada pelo acesso do membro e pelo escopo da credencial.

    curl "https://app.simplesinformatica.com.br/cco/api/cc/listar-meses?entidade_id=0190..." \
      -H "Authorization: Bearer $TOKEN"

Perfis e acesso às empresas

O que um membro — e, por consequência, uma integração — pode fazer é definido por duas escolhas independentes, feitas pelo administrador em Equipe do escritório:

• Papel: o que a pessoa pode fazer em cada empresa que alcança.
• Acesso: em quais empresas da carteira ela atua — a carteira inteira (padrão) ou somente as selecionadas.

Uma credencial de API age em nome de um membro e pode ter um escopo próprio. O token alcança a interseção entre o acesso do membro e o escopo — nunca mais do que o membro. Exemplos:

Painéis, listas e a entidade ativa devolvida no token já respeitam essas regras: uma empresa fora do alcance simplesmente não aparece, e usá-la por entidade_id responde 403 SEM_ACESSO_ENTIDADE. Mudanças de acesso valem para tokens já emitidos em até 5 minutos. Pela API, o recorte do membro é definido em PUT /escritorio/membros/{usuarioId}/entidades e o escopo da credencial em PUT /escritorio/credenciais-api/{id}/entidades.

Aviso por e-mail: cada folha importada com sucesso gera um e-mail para os administradores do escritório e os administradores da empresa, com a competência, o arquivo e quem enviou — inclusive quando o envio veio de uma integração.

O que é feito onde

Para não haver surpresa, esta é a divisão completa entre o que exige uma pessoa no navegador e o que a API faz.

O que a análise pode responder

Layout do XML de contracheque

O formato recomendado para integração é o XML padrão do Contracheque Online. Valide o arquivo contra o XSD antes de enviar: um XML válido pelo XSD é aceito pelo servidor.

Baixar XSD Baixar XML de exemplo

<LayoutContracheque>
  <Cabecalho>
    <Empresa><RazaoSocial>EMPRESA EXEMPLO LTDA</RazaoSocial><Cnpj>11222333000181</Cnpj></Empresa>
    <Competencia>202608</Competencia>
  </Cabecalho>
  <Contracheques>
    <Contracheque>
      <Servidor>…</Servidor>
      <DiscriminacaoVerbas><Verba>…</Verba></DiscriminacaoVerbas>
      <TotalVantagens>2.500,00</TotalVantagens> …
    </Contracheque>
  </Contracheques>
</LayoutContracheque>

Erros que seu sistema deve tratar

Todo erro vem como { "error": true, "message": "…", "code": "…" }. Decida pelo code; mostre o message.