Serviços

No Emites é possível cadastrar serviços que podem ser usados na hora de criar uma nova NFSe. Com os modelos de valores e serviços é possível cadastrar todas as informações necessárias para emitir o documento.

Estrutura do modelo

Note que somente os campos ´emitter_id´ e ´name´ são obrigatórios. Isso se deve ao fato de o Emites permitir o cadastro de algumas informações, e na hora de enviar uma nova NFSe, o usuário pode completar o cadastro.

Parâmetro Descrição Padrão Obrigatório Tipo de Dado Tamanho Máximo
emitter_id ID do emitente   Sim Numérico  
name Nome do serviço   Sim Caracteres  
service_amount Valor do Serviço em R$   Não Numérico 16,2
calculation_base Base de cálculo do serviço   Sim Numérico 16,2
deduction_percentage Valor das deduções para Redução da Base de Cálculo em %   Não Porcentagem 5,2
retained_iss ISS Retido. Sim (true) ou Não (false) false Não Booleano  
iss_percentage Valor da aliquota do ISS em %   Não Porcentagem 5,2
pis_percentage Valor da retenção do PIS em %   Não Porcentagem 5,2
cofins_percentage Valor da retenção do COFINS em %   Não Porcentagem 5,2
inss_percentage Valor da retenção do INSS em %   Não Porcentagem 5,2
ir_percentage Valor da retenção do IR em %   Não Porcentagem 5,2
csll_percentage Valor da retenção do CSLL em %   Não Porcentagem 5,2
discount_conditioning_percentage Valor em porcentagem de desconto concedido sobre uma determinada condição   Não Porcentagem 5,2
service_item_code Código do serviço conforme prefeitura onde o serviço é prestado   Não Caracteres 5
city_tax_code Código do serviço prestado do próprio município. Muda conforme prefeitura   Não Caracteres 20
cnae_code Classificação Nacional de Atividades Econômicas. Mais informações   Não Numérico  
description Discriminação dos serviços prestados   Não Caracteres  
city_code Código da cidade conforme IBGE. Pesquisar código da cidade   Não Numérico  
nfse_liquid_amount Valor líquido do serviço prestado em R$   Não Numérico 16,2
other_retentions_percentage Outras retenções na fonte, em %   Não Porcentagem 5,2
retained_iss_percentage Valor do ISS em %   Não Porcentagem 5,2
unconditioned_discount_percentage Desconto incondicional, é aquele concedido independentemente de qualquer condição. Valor em %   Não Porcentagem 5,2
tax_burden_amount Valor aproximado do total dos tributos   Não Numérico 15,2
tax_burden_percentage Valor aproximado do total dos tributos   Não Numérico 5,2
tax_burden_amount Fonte da carga tributária dos valores informados   Não Caracteres 10
inss_limit Limite mínimo do valor de serviço para retenção de INSS   Não Númerico 15,2
ir_limit Limite mínimo do valor de serviço para retenção de IR   Não Númerico 15,2
retained_iss_limit Limite mínimo do valor de serviço para retenção de ISS   Não Númerico 15,2
pcc_limit Limite mínimo do valor de serviço para retenção de PIS, COFINS e CSLL   Não Númerico 15,2
highlight_retentions Flag para destacar as retenções na discriminação do serviço. Veja abaixo os valores permitidos   Não Caracteres 255

Valores permitidos para highlight_retentions

Valor Descrição
ir_amount IR
pis_amount PIS
cofins_amount COFINS
csll_amount CSLL
inss_amount INSS
retained_iss_amount ISS

Criação

Para criar um novo serviço

POST /api/v1/service-values
{
    "emitter_id": 1,
    "name": "Serviços de informática",
    "service_amount": 99.90,
    "highlight_retentions": ["ir_amount", "pis_amount", "cofins_amount"]
}

Cabeçalho da resposta:

Status Code: 201
Location: https://sandbox.emites.com.br/api/v1/service-values/1
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da respostas:

{
   "_links":[{
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/services/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "emitter_id": 1,
    "name": "Serviços de informática",
    "service_amount": 0.00,
    "deduction_percentage": 0.00,
    "retained_iss": false,
    "calculation_base": 0.00,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": 0.00,
    "description": "Serviços de informática",
    "city_code": 3304557,
    "nfse_liquid_amount": 0.00,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Cálculos automáticos

Caso não seja informado os campos de ´calculation_base´ e ´nfse_liquid_amount´, os mesmos serão calculados automaticamente através dos outros valores. A base de cálculo por exemplo, é calculada com a seguinte forma:

"service_amount" - "discount_conditioning_percentage" - "unconditioned_discount_percentage" - "deduction_percentage" - "other_retentions_percentage"

Caso os valores sejam informados, o cálculo automático não é executado.

Como Utilizar

Após o modelo ser criado com sucesso, via API ou pela interface web, você já pode utiliza-lo na emissão de uma nova NFSe. Para descobrir como usar, veja a seção Utilizando modelo de Valores e Serviços na documentação da NFse.

Listagem

Para listar todos os modelos de valores e serviços:

GET /api/v1/service-values

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
    "count": 1,
    "next": null,
    "previous": null,
    "collection": [{
       "_links":[{
            "href": "https://app.emites.com.br/api/v1/service-values/1",
            "method": "GET",
            "rel": "self"
        }, {
            "href": "https://app.emites.com.br/api/v1/service-values/1",
            "method": "PUT",
            "rel": "update"
        }, {
            "href": "https://app.emites.com.br/api/v1/service-values/1",
            "method": "PATCH",
            "rel": "partial_update"
        }, {
            "href": "https://app.emites.com.br/api/v1/service-values/1",
            "method": "DELETE",
            "rel": "destroy"
        }, {
            "href": "https://app.emites.com.br/services/edit/1"
            "method": "GET"
            "rel": "html"
        }],
        "id": 1,
        "emitter_id": 1,
        "name": "Serviços de informática",
        "service_amount": 0.00,
        "deduction_percentage": 0.00,
        "retained_iss": false,
        "calculation_base": 0.00,
        "iss_percentage": 0.00,
        "pis_percentage": 0.00,
        "cofins_percentage": 0.00,
        "inss_percentage": 0.00,
        "ir_percentage": 0.00,
        "csll_percentage": 0.00,
        "discount_conditioning_percentage": 0.00,
        "service_item_code": "0105",
        "cnae_code": 0.00,
        "description": "Serviços de informática",
        "city_code": 3304557,
        "nfse_liquid_amount": 0.00,
        "city_tax_code": "010501",
        "other_retentions_percentage": 0.00,
        "retained_iss_percentage": 0.00,
        "unconditioned_discount_percentage": 0.00
    }]
}

Filtros

Para filtrar um serviço:

GET /api/v1/service-values?emitter_id=1
Parâmetro Exemplo
emitter_id /api/v1/service-values?emitter_id=1
name /api/v1/service-values?name=name

Você pode agrupar filtros, como no exemplo abaixo:

GET /api/v1/service-values?emitter_id=1&name=informatica

Todos os parâmetros devem ser URL Enconded

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da respostas:

{
   "_links":[{
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/services/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "emitter_id": 1,
    "name": "Serviços de informática",
    "service_amount": 0.00,
    "deduction_percentage": 0.00,
    "retained_iss": false,
    "calculation_base": 0.00,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": 0.00,
    "description": "Serviços de informática",
    "city_code": 3304557,
    "nfse_liquid_amount": 0.00,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Detalhes

Para acessar os detalhes de um serviço:

GET /api/v1/service-values/1

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da respostas:

{
   "_links":[{
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/services/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "emitter_id": 1,
    "name": "Serviços de informática",
    "service_amount": 0.00,
    "deduction_percentage": 0.00,
    "retained_iss": false,
    "calculation_base": 0.00,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": 0.00,
    "description": "Serviços de informática",
    "city_code": 3304557,
    "nfse_liquid_amount": 0.00,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Atualização completa

Para a atualização completa do serviço:

PUT /api/v1/service-values/1

Corpo da requisição:

{
    "emitter_id": 1,
    "name": "Outros Serviços",
    "service_amount": 99.90,
    "deduction_percentage": 0.00,
    "retained_iss": 0.00,
    "calculation_base": 99.90,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": "",
    "description": "Serviços de informática",
    "city_code": "3304557",
    "nfse_liquid_amount": 99.90,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
   "_links":[{
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/services/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "emitter_id": 1,
    "name": "Outro Serviço",
    "service_amount": 0.00,
    "deduction_percentage": 0.00,
    "retained_iss": false,
    "calculation_base": 0.00,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": 0.00,
    "description": "Serviços de informática",
    "city_code": 3304557,
    "nfse_liquid_amount": 0.00,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Atualização parcial

Para atualizar parcialmente um modelo valores e serviços:

PATCH /api/v1/service-values/1

Corpo da requisição:

{
    "name": "Outro Serviço"
}

Cabeçalho da resposta:

Status Code: 200
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Corpo da resposta:

{
   "_links":[{
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "GET",
        "rel": "self"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PUT",
        "rel": "update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "PATCH",
        "rel": "partial_update"
    }, {
        "href": "https://app.emites.com.br/api/v1/service-values/1",
        "method": "DELETE",
        "rel": "destroy"
    }, {
        "href": "https://app.emites.com.br/services/edit/1"
        "method": "GET"
        "rel": "html"
    }],
    "id": 1,
    "emitter_id": 1,
    "name": "Outro Serviço",
    "service_amount": 0.00,
    "deduction_percentage": 0.00,
    "retained_iss": false,
    "calculation_base": 0.00,
    "iss_percentage": 0.00,
    "pis_percentage": 0.00,
    "cofins_percentage": 0.00,
    "inss_percentage": 0.00,
    "ir_percentage": 0.00,
    "csll_percentage": 0.00,
    "discount_conditioning_percentage": 0.00,
    "service_item_code": "0105",
    "cnae_code": 0.00,
    "description": "Serviços de informática",
    "city_code": 3304557,
    "nfse_liquid_amount": 0.00,
    "city_tax_code": "010501",
    "other_retentions_percentage": 0.00,
    "retained_iss_percentage": 0.00,
    "unconditioned_discount_percentage": 0.00
}

Remoção

Para remover um serviço

DELETE /api/v1/service-values/1

Cabeçalho da resposta:

Status Code: 204
Date: Tue, 04 Feb 2014 17:55:19 GMT
Vary: Accept, Cookie
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

Na remoção não é retornado nenhum dado no corpo da resposta.

Cálculo de Valor Líquido da NFSe

API:

POST /api/v1/service-values/1/calculation-liquid-amount

Corpo de exemplo da requisição:

{
  "service_amount": 100.00
}

Corpo de exemplo da resposta:

{
    "liquid_amount": "94.00"
}