O trabalho da TecnoSpeed no e-Social é com sua mensageria, realizando a geração do XML a partir do TX2 ou JSON (nossos padrões de arquivos de integração) e facilitando na recepção do retorno dos eventos trazendo de uma forma mais clara (e parseada) o retorno da receita.
O Componente e-Social da Tecnospeed é uma biblioteca contendo todos os métodos necessários para emitir os eventos que a receita exige. Também é possível utilizar o e-Social através de uma API, utilizando nossas rotas para fazer todo o processo de envio e autorização dos eventos. Aqui mostramos à você o passo à passo para implementar a API no seu projeto!
- Conta TecnoSpeed
- Portal eSocial
- Consultar eventos no Portal eSocial da Tecnospeed
- Ferramenta Auxiliar (Postman)
- Como Montar uma Requisição
- Fluxo Ideal de Emissão
- Como Gerar o Arquivo de Integração
- Enviar evento
- Consultar Evento
- Verificar Ocorrências
- Correção de Informações
Conta Tecnospeed
O primeiro passo, é realizar a criação da sua Conta TecnoSpeed
A Conta TecnoSpeed permite gerenciar as configurações e ferramentas para acessar os nossos produtos e serviços em um único lugar, de forma simples e fácil.
Caso ainda não tenha uma Conta TecnoSpeed, você pode criar a sua conta agora mesmo. Com esta conta, você terá acesso à todos os produtos que a TecnoSpeed oferece.
Utilizando a conta
Após se cadastrar, você poderá visualizar o seu Token. Juntamente com o seu CNPJ ou CPF, este Token será utilizado para se autenticar na maioria de nossos serviços.
O Token juntamente com o CNPJ ou CPF será utilizado no método ConfigurarSoftwareHouse, onde você deve passar ambos como parâmetro, eles também servem para autenticar a requisição caso utilize nossa API para o envio das informações.
Acesse a sua Conta TecnoSpeed >
Portal eSocial
Para realizar a utilização da API é necessário a utilização de um certificado A1 e também realizar o cadastro do empregador em nosso Portal do eSocial.
Você deve realizar o login com os mesmo dados utilizados na Conta TecnoSpeed, após isso será possível realizar o cadastro do empregador e o cadastro do Certificado.
Cadastrando um Certificado
Para realizar o cadastro do certificado você deve clicar na aba Certificado no botão Adicionar e seguir os passos a seguir:
Preencha o formulário com a informações solicitadas e selecione o arquivo a ser enviado, lembrando que o arquivo deve ser referente a um certificado do tipo A1.
Após isso o certificado ficará disponível com identificação do Apelido escolhido.
Cadastrando um Empregador
Após realizar o cadastro do certificado você deve selecionar a aba empregador e clicar em adicionar e preencher o formulário com as informações solicitadas, vincule o certificado que irá utilizar para esse empregador e clicar em Salvar!
Também possível realizar o cadastro do certificado, empregadores e vinculador certificado através de uma requisição, basta acessar nossa documentação:
Rota - Cadastrar certificado digital
Rota - Vincular certificado digital
Consultar eventos no Portal eSocial da Tecnospeed
Para realizar a consulta de eventos no portal do eSocial da TecnoSpeed, você precisa clicar na aba Eventos. Nessa área de consulta você pode aplicar vários filtros para facilitar a busca dos eventos enviados.
Para realizar a busca dos eventos, você deve selecionar o empregador que você cadastrou, informar um período dentro de um mês desejado e selecionar um ambiente (Pré Produção ou Produção), e a versão.
Você deve selecionar qual evento você vai buscar no campo “Evento” e selecionar o status do evento que você deseja buscar (Todos, Autorizados, Rejeitados), os outros campos são opcionais. Agora basta você clicar no botão “Filtrar” para buscar os eventos.
O campo “ID Evento / Id Lote” pode ser utilizado de duas formas, utilizando o ID Evento ou ID do Lote, segue os exemplos:
Informando o ID Evento
Informando o ID do Lote
Detalhando Informações do Evento
Nas “Ações” do evento você tem a opção de visualizar com mais detalhes as informações, clicando nessa opção será aberto uma tela com as informações mais detalhadas do evento.
Dentro do detalhamento você encontrará três abas: Status, Envio e Retorno.
Status
Nessa aba você tem a hora que o evento foi enviado, código de resposta, hora de processamento do evento, caso seu evento tenha sido rejeitado, você consegue ver as ocorrências de mensagens de retorno da receita.
Envio
Nessa aba você tem o xml de envio do evento. Este xml não está assinado, pois ele contém somente dados do evento selecionado e como este evento pode estar acompanhado de outros eventos no mesmo lote, a assinatura seria do lote inteiro.
Retorno
Nessa aba você tem o xml de retorno da receita. Também sem a assinatura somente com os dados do evento especificamente selecionado.
Ferramenta Auxiliar (Postman)
Todos os exemplos da utilização da API foram produzidos e testados através do Postman, uma ferramente que permite realizar requisições de uma forma mais visível, facilitando assim o entendimento das rotinas.
O Postman pode ser baixado e instalado como uma aplicação desktop ou adicionado como uma aplicação do Google Chrome.
Importar a Coleção de Requisições
Após abrir o aplicativo, para importar uma coleção de requisições, basta clicar no botão "Import", no canto esquerdo da barra superior, selecionar a opção "Import From Link", colar o endereço abaixo e clicar novamente no botão "Import".
Endereço da coleção de requisições:
Coleção de requisições v2:
Importar a Coleção de Requisições
O Postman possui uma funcionalidade que permite visualizar uma requisição em algumas linguagens. Com a requisição aberta, basta clicar no botão "Code", no canto direito da tela, conforme é mostrado na imagem abaixo.
Após isso, será aberta uma janela com um trecho de código correspondente àquela requisição. Para alterar a linguagem, basta clicar na seta apontada para baixo, no canto superior esquerdo da janela, e selecionar a linguagem desejada.
Como Montar uma Requisição
Com a API do eSocial, nós iremos usar apenas 2 tipos de requisições, as do tipo POST e as de tipo GET.
As requisições do tipo POST servem, nesse caso, para o envio das informações para nossa API, para que possamos realizar os tratamentos necessários e a comunicação com a receita.
Já as requisições do tipo GET servem, nesse caso, para a consulta de informações, que no nosso caso será referente aos eventos enviados para a receita.
Montando a URL
A URL sempre será no padrão UrlRaiz + rota + parâmetros, sem contar com o cabeçalho da requisição (Headers) e o Body (quando necessário).
A URL raiz do eSocal é: https://api.tecnospeed.com.br/esocial/v1/evento/ e as rotas são:
Cada rota tem suas especificidades entre parâmetros e body porém, todas possuem os mesmos Headers.
Cabeçalhos de Requisições
Para a comunicação com a API do eSocial você irá usar os mesmo headers em todas as requisições, são eles:
| Nome | Descrição | Exemplo |
| cnpj_sh | CNPJ da Software House | 08187168000160 |
| token_sh | Token da Software House | Hmf3xiDgPP6nC90MO7Yy64NhEytKoOVA7AkELTZI |
Body
O body das nossas requisições serão sempre do tipo text, facilitando dessa forma a geração dos arquivos de integração.
Fluxo Ideal de Emissão
Ao utilizar a API da TecnoSpeed, o fluxo de emissão acaba ficando bem mais curto. Após realizar o cadastro do empregador e do certificado em nosso portal do eSocial, você precisará gerar o arquivos de integração (tx2), utilizar a rota de envio e após isso apenas consultar o evento para verificar o status.
Quando realizar o envio de algum evento, você vai receber um id de lote, que é o identificador único desse lote na em nossa base.
E com esse id de lote que você poderá realizar as consultar e verificar o recibo (em caso de evento autorizado) ou as ocorrências (no caso de eventos rejeitados).
Com a consulta dos eventos autorizados você receberá o retorno dos eventos totalizadores podendo assim verificar se todas as informações enviadas estão corretas.
Como Gerar o Arquivo de Integração
Os eventos são divididos em três categorias:
A TecnoSpeed criou um arquivo único de integração (tx2), onde as mudanças de leiaute na receita influencia de forma menos impactante no momento do desenvolvimento, evitando retrabalho e agilizando as atualizações entre versões de leiaute da receita
Existem algumas boas praticas na geração do tx2 que a TecnoSpeed recomenda, para o eSocial e indispensável colocar todos os valores monetários separados apenas pelo decimal e com o ponto "." .
A geração do arquivo se torna bem simples, sendo necessário seguir as regras da receita e realizar o preenchimento com as informações dos clientes.
Dicionário de Dados
Para gerar o arquivo de integração utilizando um arquivo TX2, é necessário seguir o Dicionário de Dados. Aqui nós veremos como ler as colunas deste dicionário, como iniciar e concluir um arquivo e como informar os grupos que podem se repetir.
O Dicionário de dados é uma tabela com os campos e algumas informações sobre cada campo. A tabela abaixo exemplifica o que significa cada coluna do dicionário.
| Coluna | Função |
| # | Identificador do campo, é utilizado na montagem do nome do campo no tx2. |
| Registro/Campo | Nome do campo |
| Registro Pai | Registro que identifica a hierarquia do campo em questão |
| Tam | Tamanho máximo que o campo pode possuir |
| Ocor | Ocorrência do campo/bloco, identifica os campos e blocos que são obrigatório ou não e quais podem ter múltiplas ocorrências. |
| Desc | Descrição do campo e validação que pode ser aplicadas no mesmo. |
O nome do campo do Tx2 seria a junção do Registro/Campo_#, exemplo tpAmb_4.
Inicializando e Finalizando o arquivo de integração
Para indicar o início e o fim dos dados da nota, é necessário utilizar a o comando INCLUIRSXXXX no começo e o comando SALVARSXXXX no final da inclusão dos campos. Entre estes comandos, os campos devem ser incluídos seguindo o formato exemplificado abaixo.
O XXXX é referente ao evento que está enviando, por exemplo, ao enviar o evento S-1010 você irá informar: INCLUIRS1010 e SALVARS1010
Exemplo da estrutura em TX2:
INCLUIRS1010
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
...
SALVARS1010
Informando os Grupos que podem se repetir
Para indicar o início e o fim dos grupos que podem se repetir, é necessário utilizar a o comando INCLUIR(NOMEDOGRUPO) no começo e o comando SALVAR(NOMEDOGRUPO) no final do grupo. Entre estes comandos, os campos devem ser incluídos seguindo o formato exemplificado abaixo.
O (NOMEDOGRUPO) é referente ao grupo que vou repetir, por exemplo se terei varias ocorrencias do grupo IDEPROCESSOIRRF_35 eu colocarei: INCLUIRIDEPROCESSOIRRF_35 e SALVARIDEPROCESSOIRRF_35
Exemplo da estrutura em TX2:
INCLUIRIDEPROCESSOIRRF_35
nrProc_36=
codSusp_37=
SALVARIDEPROCESSOIRRF_35
INCLUIRIDEPROCESSOIRRF_35
nrProc_36=
codSusp_37=
SALVARIDEPROCESSOIRRF_35
Além disso tudo, no começo do lote, as primeiras informações devem ser:
cpfcnpjtransmissor=08187168000160
cpfcnpjempregador=08187168000160
idgrupoeventos=1
versaomanual=S.01.00.00
ambiente=2
Todas essas informações devem obrigatoriamente estar preenchidas em todas as requisições.
Enviar evento
Para realizar envio do evento para a Receita é necessário possuir o tx2 dos eventos gerados e o cadastro do empregador e do certificado em nosso portal.
Com essas informações basta gerar a requisição de envio utilizando a rota enviar/tx2 e armazenar o id de lote retornado por essa requisição. Essa rota, faz a geração do XML a assinatura e envio para da receita.
Caso deseje, é possível gerar apenas o XML sem a a assinatura, esse caso basta utilizar a rota: gerar/xml.
Consultar Evento
Com a consulta dos eventos é possível verificar o retorno da receita bem como o XML enviado e o XML de retorno.
A forma mais comum de consultar os eventos é utilizando o Id de lote (que é retornado no envio do evento), também é possível consultar os eventos através do id do evento e do recibo. Veja a diferença deles em nosso post!
A consulta permite também que você verifique o retorno dos eventos totalizadores:
Para recepcionar os seus valores de forma mais fácil, a TecnoSpeed parseia os dados do evento, todo o retorno vem em formato JSON para facilitar a navegação entre as informações do evento.
Verificar Ocorrências
Quando você receber o retorno da consulta do lote é possível que ele tenha retornado com ocorrências, essas ocorrências, indicam erros no arquivo, tais erros podem ser corrigidos para que o lote seja enviado novamente.
Existem 2 tipos de ocorrências, as ocorrências do lote e do evento.
Ocorrências no Lote
Ocorrências no lote são geradas devido a alguma falha na comunicação ou erro no lote como um todo, não envolve informações dos eventos contidos no lote.
Ocorrências do Evento
Já as ocorrências no evento são geradas devido a algum erro nas informações enviadas, desde regra de negocio da empresa até a informação incorreta de algum valor que a receita consiga consultar. Você pode verificar todos os códigos de retorno da receita em nosso post.
Correção de Informações
No eSocial é possível realizar a correção de informações já enviadas e a exclusão de eventos que foram enviados erroneamente. Para isso temos as alterações e exclusões dos eventos. Eles são diferentes para os eventos iniciais e de tabela para com os demais eventos.
Alteração de Eventos Iniciais ou de Tabela
Para realizar uma retificação dos eventos iniciais ou de tabela é necessário utilizar a Tag ALTERAR no lugar da Tag INCLUIR, conforme exemplo de ambos os eventos.
É importante lembrar que os campos de identificação devem ser enviado igual ao do evento que foi previamente autorizado. Os campos de identificação são os campos que não podem se repetir em mais de um evento, geralmente são os primeiros 3 grupo e estão identificados com as 3 tags, INCLUIR, ALTERAR e EXCLUIR.
Exemplo:
Para alterar a data de validade desses eventos é necessário informar os campos do grupo novaValidade que terá um id diferente para cada evento Inicial ou de tabela.
Exemplo:
Se você enviar o arquivo:
INCLUIRS1000
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
nrInsc_9=13930441
iniValid_13=2017-07
fimValid_14=
nmRazao_15=TECNOSPEED TECNOLOGIA DA INFORMACAO
classTrib_16=99
natJurid_17=2054
indCoop_18=0
indConstr_19=0
indDesFolha_20=0
indOptRegEletron_21=0
indEntEd_23=N
indEtt_24=N
nrRegEtt_25=
ideMinLei_27=
nrCertif_28=
dtEmisCertif_29=
dtVencCertif_30=
nrProtRenov_31=
dtProtRenov_32=
dtDou_33=
pagDou_34=
nmCtt_36=João da Silva
cpfCtt_37=52406715167
foneFixo_38=4430379500
foneCel_39=7867834687
email_40=
nrSiafi_42=
ideEFR_44=
cnpjEFR_45=
nmEnte_47=
uf_48=
codMunic_49=
indRPPS_50=
subteto_51=
vrSubteto_52=
indAcordoIsenMulta_54=
INCLUIRSOFTWAREHOUSE_55
cnpjSoftHouse_56=13930441000134
nmRazao_57=Empresa de Teste
nmCont_58=Nome do Contato
telefone_59=4430303030
email_60=
SALVARSOFTWAREHOUSE_55
indSitPJ_63=0
indSitPF_65=
SALVARS1000
E precisar incluir ou alterar as datas de validade do mesmo, você irá enviar o arquivo:
ALTERARS1000
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
nrInsc_9=13930441
iniValid_13=2017-07
fimValid_14=
nmRazao_15=TECNOSPEED TECNOLOGIA DA INFORMACAO
classTrib_16=99
natJurid_17=2054
indCoop_18=0
indConstr_19=0
indDesFolha_20=0
indOptRegEletron_21=0
indEntEd_23=N
indEtt_24=N
nrRegEtt_25=
ideMinLei_27=
nrCertif_28=
dtEmisCertif_29=
dtVencCertif_30=
nrProtRenov_31=
dtProtRenov_32=
dtDou_33=
pagDou_34=
nmCtt_36=João da Silva
cpfCtt_37=52406715167
foneFixo_38=4430379500
foneCel_39=7867834687
email_40=
nrSiafi_42=
ideEFR_44=
cnpjEFR_45=
nmEnte_47=
uf_48=
codMunic_49=
indRPPS_50=
subteto_51=
vrSubteto_52=
indAcordoIsenMulta_54=
INCLUIRSOFTWAREHOUSE_55
cnpjSoftHouse_56=13930441000134
nmRazao_57=Empresa de Teste
nmCont_58=Nome do Contato
telefone_59=4430303030
email_60=
SALVARSOFTWAREHOUSE_55
indSitPJ_63=0
indSitPF_65=
iniValid_66=2017-05
fimValid_67=2017-09
SALVARS1000
*Os campos: tpAmb_4, procEmi_5, verProc_6, tpInsc_8, nrInsc_9, iniValid_13, fimValid_14 são utilizados para a identificação do evento pela receita, logo, devem ser iguais ao evento autorizado.
Caso precisa apenas alterar alguma informação, como o classTrib_16 você pode enviar o arquivo da seguinte forma:
ALTERARS1000
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
nrInsc_9=13930441
iniValid_13=2017-07
fimValid_14=
nmRazao_15=TECNOSPEED TECNOLOGIA DA INFORMACAO
classTrib_16=01
natJurid_17=2054
indCoop_18=0
indConstr_19=0
indDesFolha_20=0
indOptRegEletron_21=0
indEntEd_23=N
indEtt_24=N
nrRegEtt_25=
ideMinLei_27=
nrCertif_28=
dtEmisCertif_29=
dtVencCertif_30=
nrProtRenov_31=
dtProtRenov_32=
dtDou_33=
pagDou_34=
nmCtt_36=João da Silva
cpfCtt_37=52406715167
foneFixo_38=4430379500
foneCel_39=7867834687
email_40=
nrSiafi_42=
ideEFR_44=
cnpjEFR_45=
nmEnte_47=
uf_48=
codMunic_49=
indRPPS_50=
subteto_51=
vrSubteto_52=
indAcordoIsenMulta_54=
INCLUIRSOFTWAREHOUSE_55
cnpjSoftHouse_56=13930441000134
nmRazao_57=Empresa de Teste
nmCont_58=Nome do Contato
telefone_59=4430303030
email_60=
SALVARSOFTWAREHOUSE_55
indSitPJ_63=0
indSitPF_65=
SALVARS1000
Alteração de Eventos Periódicos e Não Periódicos
Para os eventos periódicos e não periódicos é necessário enviar um novo evento com as alterações preenchendo os campos indRetif_4 e nrRecibo_5.
O campo indRetif_4 deve ir com o valor 2, indicando ser uma retificação. O campo nrRecibo_5 deverá conter o número de recibo do evento autorizado que será retificado.
Exemplo:
Regras a considerar para a geração do Tx2
INCLUIRS1207
indRetif_4=2
nrRecibo_5=127309-08-2010-1809-128409
indApuracao_6=1
perApur_7=2017-08
tpAmb_8=2
procEmi_9=1
verProc_10=1.0
tpInsc_12=1
nrInsc_13=13930441
cpfBenef_15=06332328827
INCLUIRDMDEV_16
tpBenef_17=1
nrBenefic_18=123
ideDmDev_19=123
INCLUIRITENS_20
codRubr_21=1
ideTabRubr_22=
vrRubr_23=1
SALVARITENS_20
SALVARDMDEV_16
SALVARS1207
Exclusão de Eventos Iniciais ou de Tabela
Para realizar uma exclusão dos eventos Iniciais ou de Tabela é necessário utilizar a Tag EXCLUIR no lugar da Tag INCLUIR, conforme exemplo de ambos os eventos.
Exemplo:
EXCLUIRS1000
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
nrInsc_9=13930441
iniValid_13=2017-07
fimValid_14=
SALVARS1000
Onde você estará informando apenas os dados de localização do evento. Esses dados devem ser os mesmo do arquivo que foi autorizado.
Exclusão de Eventos Periódicos e Não Periódicos
Para os eventos periódicos e não periódicos é necessário enviar o evento S-3000 - Exclusão de Eventos.
Exclusão da Base de Dados
A receita disponibiliza uma forma para que você possa excluir toda a sua base de dados no ambiente de Produção Restrita.
Para isso você deve enviar a inclusão de um S-1000 informando o campo de classificação tributária com o valor "00", desta forma:
classTrib_16=00
Só é possível utilizar esse processo no ambiente de Produção Restrita, tpAmb_4=2
Exemplos:
Regras a considerar para a geração do Tx2
INCLUIRS1000
tpAmb_4=2
procEmi_5=1
verProc_6=1.0
tpInsc_8=1
nrInsc_9=13930441
iniValid_13=2017-07
fimValid_14=
classTrib_16=00
natJurid_17=2054
indCoop_18=0
indConstr_19=0
indDesFolha_20=0
indOptRegEletron_21=0
indEntEd_23=N
indEtt_24=N
nrRegEtt_25=
ideMinLei_27=
nrCertif_28=
dtEmisCertif_29=
dtVencCertif_30=
nrProtRenov_31=
dtProtRenov_32=
dtDou_33=
pagDou_34=
nmCtt_36=João da Silva
cpfCtt_37=52406715167
foneFixo_38=4430379500
foneCel_39=7867834687
email_40=
nrSiafi_42=
ideEFR_44=
cnpjEFR_45=
nmEnte_47=
uf_48=
codMunic_49=
indRPPS_50=
subteto_51=
vrSubteto_52=
indAcordoIsenMulta_54=
INCLUIRSOFTWAREHOUSE_55
cnpjSoftHouse_56=13930441000134
nmRazao_57=Empresa de Teste
nmCont_58=Nome do Contato
telefone_59=4430303030
email_60=
SALVARSOFTWAREHOUSE_55
indSitPJ_63=0
indSitPF_65=
SALVARS1000
Lembrando sempre que, no começo do lote, as primeiras informações devem ser:
cpfcnpjtransmissor=08187168000160
cpfcnpjempregador=08187168000160
idgrupoeventos=1
versaomanual=S.01.00.00
ambiente=2
Todas essas informações devem obrigatoriamente estar preenchidas.
Comentários
0 comentário
Por favor, entre para comentar.