Integrações cadastrais
Recursos para integração de cadastros
POST https://tributos.suite.betha.cloud/integracoes/v1/bairros\
POST https://tributos.suite.betha.cloud/integracoes/v1/distritos\
POST https://tributos.suite.betha.cloud/integracoes/v1/logradouros\
POST https://tributos.suite.betha.cloud/integracoes/v1/contribuintes\
POST https://tributos.suite.betha.cloud/integracoes/v1/contadores\
POST https://tributos.suite.betha.cloud/integracoes/v1/economicos
Detalhamento dos recursos
As APIs disponibilizadas recebem um JSON no corpo da requisição, contendo as propriedades preenchidas conforme os esquemas a seguir.
Deve ser utilizado o método POST tanto para criação quanto para alteração de um registro, sendo tal determinação feita pela presenção ou não da propriedade id no JSON (se houver id, será feita uma busca pelo registro e o processo é de alteração; sem id será sempre tratado como criação).
Para alteração cadastral, devem ser omitidos do JSON os atributos que não devem ser alterados (exceto o id, o qual é utilizado para identificação do registro já existente).
Definições sobre o cadastro Econômicos/empresas
O serviço de criação de econômicos/empresas será feita por um único endpoint.
As seguintes dependências obrigatórias serão buscadas pelas suas chaves de negócio e devem estar cadastradas no Tributos Cloud:
- município
- bairro
- logradouro
Caso não seja possível identificar um único registro para cada uma dessas dependências, será retornada uma validação e a empresa não será criada.
As seguintes dependências serão buscadas pelas suas chaves de negócio e, caso não existam, os registros serão criados junto a criação da empresa, e vinculados à mesma, utilizando os dados informados no json:
- contribuinte
- contador
- sócios
A lista de CNAEs do econômico não é obrigatória e as CNAEs são identificadas pelos códigos oficiais da lista federal (7 dígitos). Caso seja informada, é obrigatório indicar uma CNAE como principal.
Caso seja necessário desativar alguma CNAE que já consta no cadastro econômico, você deverá fazer o seguinte:
- No objeto cnae, deverão constar todas aquelas CNAEs que devem permanecer ativas no cadastro;
- As CNAES não passadas na lista serão desativados, caso a propriedade configuracoesAjustes.cnaes.desativaNaoEnviados estiver como true e a configuracoesAjustes.cnaes.dtPadraoDesativacao possuir uma data válida.
- A lista de serviços do econômico não é obrigatória e os serviços são identificados pelos códigos oficiais da lista federal (4 dígitos). Caso seja informado, é obrigatório indicar um serviço como principal.
- O campo obrigatório tipoContribuinte pode ser informado com o valor NORMAL caso não haja dados no sistema do cliente para uma definição específica. As opções desse campo são:
- NORMAL
- CONSTRUTORA_EMPREITEIRA
- SERVICO_POR_CONTA
- ENTIDADE_ESPECIAL
- CONDOMINIO
- O campo obrigatório regimeCobrancaIss pode ser informado SEM_COBRANCA caso não haja dados no sistema do cliente para uma definição específica. As opções desse campo são:
- HOMOLOGADO
- FIXO
- ESTIMADO
- ARBITRADO
- SEM_COBRANCA
- O endereço de correspondência da empresa pode ser informado de três formas, utilizando o campo obrigatório tipoEnderecoCorrespondencia:
- ECONOMICO: nesse caso, o endereço de correspondência é o próprio endereço informado na empresa/econômico e não é necessário informar os campos desse endereço separadamente.
- PRINCIPAL_CONTRIBUINTE: nesse caso, o de correspondência é o endereço principal do contribuinte/pessoa jurídica vinculado à empresa.
- OUTRO: por último, se o endereço de correspondência for diferente do endereço da empresa e do contribuinte, pode ser informado um novo endereço separadamente pelo campo enderecoCorrespondencia.
- Em contribuinte/pessoa jurídica, nos campos de natureza jurídica e qualificação do responsável, deve ser utilizado o código oficial de acordo com a tabela federal. Por exemplo, para a natureza Fundo Privado e a Qualificação Administrador:
- "idNaturezaJuridica": 3247
- "idQualificacao": 5
- O campo obrigatório principal, caso não seja informado, será controlado internamente na geração do econômico. Se existir um outro econômico principal para o CPF/CNPJ, o econômico sendo criado não será principal. Se não existir, o econômico será definido como principal para aquele CPF/CNPJ.
- O campo codigo no serviço de econômico pode ser informado manualmente pelo usuário do serviço de integração, o qual é equivalente à inscrição municipal. Caso não seja informado, será gerado automaticamente.
- Todo econômico deve possuir uma movimentação com a situação INICIO e a data de início das atividades.
- Para alterar a situação de um econômico existente, é necessário adicionar outra movimentação após a movimentação inicial.
- A alteração de empresas/econômicos é feita pelo mesmo serviço de criação. Para que a ação seja considerada uma alteração, deve ser informado o campo id do econômico.
/bairros
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do bairro | Long |
| nome | Nome do bairro | String |
| nomeMunicipio | Nome do município | String |
| uf | Sigla da Unidade Federativa | String |
/distritos
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do distrito | Long |
| nome | Nome do distrito | String |
| nomeMunicipio | Nome do município | String |
| uf | Sigla da Unidade Federativa | String |
/Logradouros
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do logradouro | Long |
| nome | Nome do logradouro | String |
| tipo | Tipo do logradouro (Rua, Avenida, etc) | String |
| nomeMunicipio | Nome do município | String |
| uf | Sigla da Unidade Federativa | String |
/contribuintes
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do contribuinte/pessoa | Long |
| nome | Nome do contribuinte | String |
| tipo | Tipo do contribuinte (pessoa física ou jurídica) | FISICA, JURIDICA |
| cpfCnpj | CPF ou CNPJ do contribuinte | String |
| nome | Nome do contribuinte | String |
| nomeFantasia | Nome fantasia (PJ) ou social (PF) | String |
| site | Sigla da Unidade Federativa | String |
| pessoaJuridica | Dados da pessoa jurídica | PessoaJuridica |
| socios | Listagem de sócios da pessoa jurídica | List |
| enderecos | Listagem de endereços do contribuinte | List |
| telefones | Listagem de telefones do contribuinte | List |
| camposAdicionais | Mapa de campos adicionais do contribuinte | Map |
Subtipos:
- pessoaJuridica: Para os contribuintes que forem do tipo pessoa jurídica, poderá ser informado um objeto JSON contendo os seguintes atributos, conforme a necessidade de preenchimento do lado.
|
|---|
- movimentacoesSimplesNacional: Listagem com as movimentações que determinam qual a opção do contribuinte quanto ao Simples Nacional em determinadas datas:
|
|---|
- movimentacoesMei: Listagem com as movimentações que determinam qual a opção do contribuinte quanto ao Simples Nacional em determinadas datas. O objeto que deve ser informado na lista possui os mesmos campos da movimentacoesSimplesNacional.
- socios: Listagem com as pessoas que compõe o quadro societário da pessoa jurídica.
|
|---|
- telefones: listagem de telefones da pessoa, sendo necessário definir exatamente um como principal:
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| principal | Identificação do principal telefone do contribuinte | SIM, NAO |
| tipo | Tipo do telefone | FIXO, CELULAR, FAX |
| numero | Número completo do telefone | Formato(10 ou 11 dígitos): 9999999999 ou 99999999999 |
| descricao | Campo para informação extra de identificação | String |
- enderecos: listagem de endereços da pessoa, sendo necessário definir exatamente um como principal:
|
|---|
- camposAdicionais: mapa no formato chave-valor de valores adicionais conforme os campos adicionais configurados para o cadastro no Tributos Cloud. Na busca do campo pela chave são desconsiderados caracteres especiais e espaços, enquanto o valor do campo deve ser informado sempre como String, conforme o exemplo abaixo:
|
|---|
(exemplo de campo adicional, todos válidos conforme o cadastro acima)
|
|---|
/contadores
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do contador | Long |
| nroCrc | Número do CRC | String |
| dtValidadeCrc | Data de validade do CRC | LocalDate |
| contribuinte | Contribuinte referente ao contador | Contribuinte |
| escritorioContabilidade | Registro de contador referente ao escritório de contabilidade o qual o contador pertence | Contador |
| associados | Listagem de contadores associados ao escritório de contabilidade | List |
| cbos | Listagem de CBO(s) do contador | List |
Subtipos:
- contribuinte: para identificação do contribuinte a ser vinculado ao contador, deve ser informado um objeto JSON com um ou mais dos seguintes atributos:
|
|---|
escritorioContabilidade: somente deve ser informado caso o contador sendo inserido ou alterado seja pessoa física. O escritório deve ser um registro de contador do tipo pessoa jurídica. Os atributos do objeto JSON disponíveis são os mesmos do contribuinte (id, codigo, cpfCnpj, nome).
associados: somente deve ser informado caso o contador sendo inserido ou alterado seja pessoa jurídica (escritório de contabilidade). O atributo deve ser uma listagem de contadores, sendo cada contador identificado pelos mesmos atributos já descritos anteriormente (id, codigo, cpfCnpj, nome).
cbos: somente deve ser informado caso o contador sendo inserido ou alterado seja pessoa física. O atributo deve ser uma listagem de objeto contendo uma ou mais das propriedades da tabela abaixo:
|
|---|
Exemplos:
Inserção de contador:
|
|---|
Alteração de contador:
|
|---|
/atividades-economicas
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do contador | Long |
| classificacao | Classificação da atividade | AGROPECUARIAPESCA, INDUSTRIA, MEIOAMBIENTE, COMERCIO, SERVICO |
| codigoCnae | Código da CNAE associada à atividade | Long |
| codigoListaServico | Código do serviço associado à atividade | Long |
| risco | Classificação quanto ao risco | NORMAL, ALTO, MEDIO, BAIXO |
| riscoMei | Classificação quanto ao risco (MEI) | NORMAL, ALTO, MEDIO, BAIXO |
| valores | Listagem de valores da atividade | List |
| camposAdicionais | Mapa de campos adicionais | Map |
Subtipos:
- valores: Os valores de alvará, o valor de ISS e/ou o percentual da alíquota do ISS devem ser informados nessa listagem para as atividades que possuem valores padrões/compartilhados entre diversos econômicos. Por exemplo:, caso o econômico possua o serviço 1.02 -- Programação informado, sem ter sido declarada uma alíquota de ISS no próprio cadastro do econômico, será utilizada a alíquota da atividade econômica do serviço 1.02, caso ela esteja informada na listagem deste item.
|
|---|
- camposAdicionais: mapa no formato chave-valor de valores adicionais conforme os campos adicionais configurados para o cadastro no Tributos Cloud. Segue as mesmas regras e formato dos campos adicionais do contribuinte, detalhados anteriormente neste documento.
Exemplos:
|
|---|
|
|---|
/economicos
| CAMPO | DESCRIÇÃO | TIPO |
|---|---|---|
| id | Identificador interno do econômico | Long |
| idContribuinte | Identificador do contribuinte | Long |
| principal | Indicador de econômico principal do contribuinte | SIM, NAO |
| tipoContribuinte | Tipo do contribuinte | NORMAL, CONSTRUTORA_EMPREITEIRA,\ |
| SERVICO_POR_CONTA, ENTIDADE_ESPECIAL, CONDOMINIO | ||
| regimeCobrancaIss | Regime de cobrança do ISS | HOMOLOGADO, FIXO, ESTIMADO, ARBITRADO, SEM_COBRANCA |
| idImovel | Identificador interno do imóvel onde é localizado o econômico | Long |
| idContador | Identificador interno do contador/escritório de contabilidade | Long |
| idBanco | Identificador interno do banco, para econômicos com tipoContribuinte SERVICO_POR_CONTA | Long |
| cep | CEP do econômico | String |
| numeroEndereco | Número do endereço | String |
| complementoEndereco | Complemento do endereço | String |
| descricaoEndereco | Informação adicional/descritiva do endereço | String |
| apartamento | Informação do apartamento do endereço | String |
| bloco | Bloco do endereço | String |
| idMunicipio | Identificador do município | Long |
| idLogradouro | Identificador do logradouro | Long |
| idBairro | Identificador interno do bairro | Long |
| idLoteamento | Identificador do loteamento | Long |
| idDistrito | Identificador do distrito | Long |
| idCondominio | Identificador do condominio | Long |
| tipoEnderecoCorrespondencia | Tipo de endereço de correspondência:\ |
- o próprio endereço do econômico;\
- o endereço principal do contribuinte;\
- um outro endereço, que deve ser informado como objeto no campo enderecoCorrespondencia, contendo os mesmos campos de endereço do econômico. | ECONOMICO, PRINCIPAL_CONTRIBUINTE,\ OUTRO | | cnaes | Listagem de cnaes/atividades do econômico | List | | servicos | Listagem de serviços do econômico | List | | prepostos | Listagem de telefones do contribuinte | List | | movimentacoes | Listagem de movimentações de situação | List | | camposAdicionais | Mapa de campos adicionais do contribuinte | Map |
Subtipos:
- cnaes: listagem com as CNAEs/atividades exercidas pelo econômico:
|
|---|
- Lista de serviços: listagem com os items da lista de serviço exercidos pelo econômico:
|
|---|
- movimentacoes: listagem com as movimentações de situação do econômico:
|
|---|
- prepostos: listagem dos prepostos vinculados ao econômico:
|
|---|
- camposAdicionais: mapa no formato chave-valor de valores adicionais conforme os campos adicionais configurados para o cadastro no Tributos (Cloud). Segue as mesmas regras e formato dos campos adicionais do contribuinte, detalhados anteriormente neste documento.
Exemplos:
|
|---|
|
|---|
