Sincronize certificados de isenção do imposto sobre vendas dos EUA com um perfil de cliente.
Se vende a revendedores, organismos públicos ou organizações sem fins lucrativos, esses compradores têm certificados de isenção que os isentam do imposto sobre vendas em determinados estados. A Zonos guarda esses certificados num perfil de cliente para que um comprador isento possa ser reconhecido no checkout.
As isenções são registadas por jurisdição. Um cliente isento na Carolina do Sul não fica automaticamente isento no Texas, pelo que cada estado para o qual o cliente tem um certificado é um registo separado, com as suas próprias datas e número de certificado.
As isenções associam-se a um cliente já existente, pelo que a sincronização é feita em duas chamadas: criar o cliente e, em seguida, sincronizar os respetivos certificados. Ambas são identificadas pelo seu próprio ID de cliente — o mesmo customerId que utiliza noutras partes do Checkout. A Zonos nunca exige que guarde um ID interno.
As isenções ainda não são aplicadas às cotações de landed cost
Já pode sincronizar e gerir isenções hoje, e os registos ficam guardados no perfil do cliente.
A dedução de uma isenção do imposto num landed cost estará disponível em breve, pelo que uma
isenção sincronizada ainda não altera o imposto cotado a um comprador. Sincronizar agora
significa que os seus certificados já estarão prontos quando isso acontecer.
checkoutCustomerUpsert cria um perfil de cliente ou atualiza-o se já existir um para esse customerId. Ao contrário de checkoutCustomerProfileAuthenticate, não exige que o comprador esteja presente, pelo que pode carregar a sua lista de clientes antecipadamente. Consulte criar ou atualizar um perfil sem comprador para conhecer o comportamento completo dos campos.
Como a correspondência é feita pelo customerId, chamá-la repetidamente atualiza o mesmo perfil em vez de criar duplicados. Pode executá-la com segurança em toda a sua lista de clientes em cada sincronização.
A lista é a referência.taxExemptions é o conjunto completo de isenções do cliente, não uma lista de alterações. Qualquer isenção já registada que não conste da lista é removida — é assim que um certificado revogado deixa de ser aplicado. Enviar uma lista parcial remove silenciosamente tudo o que ficar de fora.
Cada registo é uma isenção. Não é possível registar que um cliente não está isento num determinado local — consulte a nota abaixo.
Remover todas as isenções corresponde a uma lista vazia. Para limpar os certificados de um cliente, envie-o com "taxExemptions": []. Deixar o cliente totalmente de fora do payload mantém os seus registos existentes inalterados.
Envie apenas as jurisdições em que o cliente é isento
A Zonos não tem um registo de "não isento" — uma jurisdição ou está na lista ou não está. Se o
seu sistema guarda jurisdições isentas e não isentas em conjunto, filtre apenas as isentas antes
de sincronizar. Um registo não isento é indistinguível de um certificado real, pelo que é aceite
em vez de rejeitado, e o cliente será tratado como isento nesse estado.
exemptionReason descreve o motivo pelo qual o cliente está isento. É opcional e assume UNSPECIFIED por predefinição, mas compensa indicá-lo — consulte abaixo.
Valor↕
Aplica-se a↕
RESALE
Mercadorias compradas para revenda, não para consumo
FEDERAL_GOVERNMENT
Uma agência ou departamento federal dos EUA
STATE_LOCAL_GOVERNMENT
Um órgão estadual, condado, município ou distrito escolar
TRIBAL_GOVERNMENT
Uma tribo reconhecida federalmente ou membro de uma tribo
CHARITABLE
Uma organização beneficente sem fins lucrativos
RELIGIOUS_ORGANIZATION
Uma igreja ou outra organização religiosa
EDUCATIONAL_ORGANIZATION
Uma escola ou universidade
DIRECT_PAY
Um comprador titular de uma licença de pagamento direto que entrega o imposto por conta própria
OTHER
Outros casos, incluindo diplomata estrangeiro, produção agrícola, produção industrial e correio direto
UNSPECIFIED
Nenhum motivo indicado
Os motivos dividem-se em dois grupos, e a diferença é importante. Os motivos baseados na entidade — governo, beneficência, religião, educação — isentam o comprador independentemente do que compra. Os motivos baseados na utilização, sobretudo RESALE, abrangem apenas as mercadorias elegíveis: um certificado de revenda abrange o inventário que o comprador vai revender, não o mobiliário de escritório na mesma encomenda.
Sem um motivo, a Zonos não consegue distinguir os dois casos e só pode isentar encomendas inteiras, o que é mais difícil de justificar no caso dos certificados de revenda. Se a maioria das suas isenções for de revenda, enviar RESALE como valor predefinido e indicar as exceções individualmente costuma dar muito menos trabalho do que classificar cada cliente.
exemptionReference é o número impresso na documentação de isenção do cliente. Consoante o estado e o tipo de isenção, pode ser um número de licença de revenda ou de vendedor, um número de certificado de isenção estadual, um número de licença de pagamento direto ou um número de identificação fiscal federal.
É obrigatório em todos os registos. Guarde-o e envie-o exatamente como aparece no certificado — os formatos variam muito consoante a jurisdição (SR EAA 12-345678, 85-8012345678C-9, 12-3456789), e a Zonos preserva o valor tal como foi enviado, removendo apenas os espaços em branco no início e no fim. Não altere maiúsculas e minúsculas nem remova hífenes ou espaços.
Por motivos de privacidade, exemptionReference pode ser enviado, mas não é devolvido quando se
consultam as isenções, uma vez que pode conter um número de identificação fiscal federal.
Os registos são validados um a um. Um registo rejeitado é indicado em rejected e não faz falhar o resto do lote, nem altera a isenção já registada para essa jurisdição.
Código↕
Causa↕
UNKNOWN_CUSTOMER
Nenhum cliente corresponde ao customerId. Crie o cliente primeiro
UNKNOWN_JURISDICTION
administrativeArea não é um estado, distrito ou território dos EUA reconhecido
INVALID_DATE_RANGE
expiresAt não é posterior a effectiveAt
MISSING_EXEMPTION_REFERENCE
exemptionReference está vazio
DUPLICATE_JURISDICTION
Dois registos no mesmo payload partilham país, região e data de início. O primeiro é mantido
Os clientes desconhecidos são rejeitados em vez de criados, pelo que um customerId mal escrito surge na resposta em vez de criar um perfil que nunca corresponderá a um comprador real.
Apenas as regiões administrativas dos EUA são validadas. As subdivisões de outros países são aceites tal como são enviadas.
Para remover todas as isenções de um cliente — quando este encerra a conta, por exemplo — utilize checkoutCustomerTaxExemptionsDelete. Devolve SUCCESS quer o cliente tenha isenções ou não, pelo que pode chamá-la mais de uma vez com segurança.
Isenções fiscais
Isenções fiscais
Sincronize certificados de isenção do imposto sobre vendas dos EUA com um perfil de cliente.
Se vende a revendedores, organismos públicos ou organizações sem fins lucrativos, esses compradores têm certificados de isenção que os isentam do imposto sobre vendas em determinados estados. A Zonos guarda esses certificados num perfil de cliente para que um comprador isento possa ser reconhecido no checkout.
As isenções são registadas por jurisdição. Um cliente isento na Carolina do Sul não fica automaticamente isento no Texas, pelo que cada estado para o qual o cliente tem um certificado é um registo separado, com as suas próprias datas e número de certificado.
As isenções associam-se a um cliente já existente, pelo que a sincronização é feita em duas chamadas: criar o cliente e, em seguida, sincronizar os respetivos certificados. Ambas são identificadas pelo seu próprio ID de cliente — o mesmo
customerIdque utiliza noutras partes do Checkout. A Zonos nunca exige que guarde um ID interno.Esta funcionalidade está disponível apenas para integrações personalizadas por API.
Já pode sincronizar e gerir isenções hoje, e os registos ficam guardados no perfil do cliente. A dedução de uma isenção do imposto num landed cost estará disponível em breve, pelo que uma isenção sincronizada ainda não altera o imposto cotado a um comprador. Sincronizar agora significa que os seus certificados já estarão prontos quando isso acontecer.
Criar ou atualizar o cliente
checkoutCustomerUpsertcria um perfil de cliente ou atualiza-o se já existir um para essecustomerId. Ao contrário decheckoutCustomerProfileAuthenticate, não exige que o comprador esteja presente, pelo que pode carregar a sua lista de clientes antecipadamente. Consulte criar ou atualizar um perfil sem comprador para conhecer o comportamento completo dos campos.mutation checkoutCustomerUpsert($input: CheckoutCustomerProfileInput!) {checkoutCustomerUpsert(input: $input) {customerIdemailnamephone}}Como a correspondência é feita pelo
customerId, chamá-la repetidamente atualiza o mesmo perfil em vez de criar duplicados. Pode executá-la com segurança em toda a sua lista de clientes em cada sincronização.Sincronizar isenções fiscais
checkoutCustomerTaxExemptionsSyncaceita vários clientes de uma só vez. Cada entrada substitui o conjunto completo de isenções desse cliente.mutation checkoutCustomerTaxExemptionsSync($input: [CheckoutCustomerTaxExemptionSyncInput!]!) {checkoutCustomerTaxExemptionsSync(input: $input) {customerIdaccepted {idcountryCodeadministrativeAreaeffectiveAtexpiresAtexemptionReason}rejected {codemessageadministrativeAreaeffectiveAt}}}Se
expiresAtfor omitido, o certificado não expira. SeexemptionReasonfor omitido, assumeUNSPECIFIEDpor predefinição.Como funciona a sincronização
Todas as sincronizações seguem três regras.
A lista é a referência.
taxExemptionsé o conjunto completo de isenções do cliente, não uma lista de alterações. Qualquer isenção já registada que não conste da lista é removida — é assim que um certificado revogado deixa de ser aplicado. Enviar uma lista parcial remove silenciosamente tudo o que ficar de fora.Cada registo é uma isenção. Não é possível registar que um cliente não está isento num determinado local — consulte a nota abaixo.
Remover todas as isenções corresponde a uma lista vazia. Para limpar os certificados de um cliente, envie-o com
"taxExemptions": []. Deixar o cliente totalmente de fora do payload mantém os seus registos existentes inalterados.A Zonos não tem um registo de "não isento" — uma jurisdição ou está na lista ou não está. Se o seu sistema guarda jurisdições isentas e não isentas em conjunto, filtre apenas as isentas antes de sincronizar. Um registo não isento é indistinguível de um certificado real, pelo que é aceite em vez de rejeitado, e o cliente será tratado como isento nesse estado.
Motivos de isenção
exemptionReasondescreve o motivo pelo qual o cliente está isento. É opcional e assumeUNSPECIFIEDpor predefinição, mas compensa indicá-lo — consulte abaixo.RESALEFEDERAL_GOVERNMENTSTATE_LOCAL_GOVERNMENTTRIBAL_GOVERNMENTCHARITABLERELIGIOUS_ORGANIZATIONEDUCATIONAL_ORGANIZATIONDIRECT_PAYOTHERUNSPECIFIEDOs motivos dividem-se em dois grupos, e a diferença é importante. Os motivos baseados na entidade — governo, beneficência, religião, educação — isentam o comprador independentemente do que compra. Os motivos baseados na utilização, sobretudo
RESALE, abrangem apenas as mercadorias elegíveis: um certificado de revenda abrange o inventário que o comprador vai revender, não o mobiliário de escritório na mesma encomenda.Sem um motivo, a Zonos não consegue distinguir os dois casos e só pode isentar encomendas inteiras, o que é mais difícil de justificar no caso dos certificados de revenda. Se a maioria das suas isenções for de revenda, enviar
RESALEcomo valor predefinido e indicar as exceções individualmente costuma dar muito menos trabalho do que classificar cada cliente.Referência da isenção
exemptionReferenceé o número impresso na documentação de isenção do cliente. Consoante o estado e o tipo de isenção, pode ser um número de licença de revenda ou de vendedor, um número de certificado de isenção estadual, um número de licença de pagamento direto ou um número de identificação fiscal federal.É obrigatório em todos os registos. Guarde-o e envie-o exatamente como aparece no certificado — os formatos variam muito consoante a jurisdição (
SR EAA 12-345678,85-8012345678C-9,12-3456789), e a Zonos preserva o valor tal como foi enviado, removendo apenas os espaços em branco no início e no fim. Não altere maiúsculas e minúsculas nem remova hífenes ou espaços.Por motivos de privacidade,
exemptionReferencepode ser enviado, mas não é devolvido quando se consultam as isenções, uma vez que pode conter um número de identificação fiscal federal.Registos rejeitados
Os registos são validados um a um. Um registo rejeitado é indicado em
rejectede não faz falhar o resto do lote, nem altera a isenção já registada para essa jurisdição.UNKNOWN_CUSTOMERcustomerId. Crie o cliente primeiroUNKNOWN_JURISDICTIONadministrativeAreanão é um estado, distrito ou território dos EUA reconhecidoINVALID_DATE_RANGEexpiresAtnão é posterior aeffectiveAtMISSING_EXEMPTION_REFERENCEexemptionReferenceestá vazioDUPLICATE_JURISDICTIONOs clientes desconhecidos são rejeitados em vez de criados, pelo que um
customerIdmal escrito surge na resposta em vez de criar um perfil que nunca corresponderá a um comprador real.Apenas as regiões administrativas dos EUA são validadas. As subdivisões de outros países são aceites tal como são enviadas.
Consultar e remover
Consulte as isenções de um cliente para confirmar que uma sincronização foi aplicada:
query checkoutCustomerTaxExemptions($customerId: String!) {checkoutCustomerTaxExemptions(customerId: $customerId) {countryCodeadministrativeAreaeffectiveAtexpiresAtexemptionReason}}Para remover todas as isenções de um cliente — quando este encerra a conta, por exemplo — utilize
checkoutCustomerTaxExemptionsDelete. DevolveSUCCESSquer o cliente tenha isenções ou não, pelo que pode chamá-la mais de uma vez com segurança.mutation checkoutCustomerTaxExemptionsDelete($customerId: String!) {checkoutCustomerTaxExemptionsDelete(customerId: $customerId)}CheckoutCustomerProfileInput CheckoutCustomerTaxExemptionSyncInput
checkoutCustomerTaxExemptionsDelete checkoutCustomerTaxExemptionsSync checkoutCustomerUpsert
Esta página foi útil?