La API JSON/REST de API .  Todas las respuestas de API son JSON (incluyendo los errores), pero son facilmente convertidas a cualquier lenguaje. Usamos códigos de status y respuesta HTTP estándar.

Para facilitar las pruebas, todos los ejemplos usan una cuenta falsa en un entorno de prueba https://staging.core.instantcard.net/api/v2/. Para implementar nuestros APIs en un ambiente de producción, debe usar el camino base

https://core.instantcard.net/api/v2/

En vez de una llave API estándar, usamos un método POST de inicio de sesión/autenticación para conseguir un token de inicio de sesión. Este token es usado en todas las llamadas que siguen. Ya que el token expira, la autenticación se requiere para cada sesión.

Nota de contactos y direcciones:
Aunque están separados en diferentes secciones, con sus propios endpoints, los contactos y las direcciones están diseñados para trabajar en conjunto. Con este fin, los contactos individuales pueden vincularse a direcciones individuales, y viceversa. Si usted desea tratarlos como una sola entidad, puede definir todos los campos a través de los endpoints de DIRECCIONES (que acepta todos los parámetros que definen un contacto).

Es posible que usted desée ver una llamada ejemplo en un lenguaje que no hemos mostrado. En este caso, porfavor contactáctenos y lo agregaremos lo más pronto posible.

Para probar el API por usted mismo sin una cuenta, use estas credenciales:

El API de InstantCard fue diseñado con ciertos flujos de trabajo en mente. Por ejemplo, al crear una tarjeta desarrollamos un sistema dedicado a crear un borrador, obtener vista previa de ese borrador y actualizarlo si requiere modificaciones. Así que, siéntase en libertad de revisar los flujos recomendados a a continuación. Notará que varios de nuestros endpoints no entran en estos ejemplos, y no son requeridos por el cliente típico.

Si hay algún flujo de trabajo que le gustaría ver pero no está enlistado aquí, por favor,  Contáctenos.

Flujo de Autenticación

Su token de autenticación es un parámetro requerido para cualquier llamada subsecuente. 

1. Inicio de Sesión
   • Use el endpoint AUTHENTICATE USER → para obtener su token de autenticación.
2. Perfil de Usuario
   • Use el endpoint FETCH USER PROFILE → para obtener la información de usuario.

Crear una Nueva Tarjeta

La API fue diseñada para crear las tarjetas como borradores, obtener una vista previa del borrador y actualizar el diseño de ser necesario o finalizar.

1. Crear Borrador
   • Use el endpoint CREATE A NEW CARD → para crear su borrador. (Recuerde, esto no finaliza la tarjeta, y no estará disponible para imprimir todavía).
2. Vista Previa
   • Use el endpoint PREVIEW CARD → para revisar el borrador creado (esto es particularmente útil cuando se usa la herramienta de corte de imagen, al verficar que la tarjeta se vea como usted quiere).
3. Si hay algún problema, Actualice Tarjeta, y vuelva a vista previa.
   • Use el endpoint UPDATE CARD → para corregir cualquier error encontrado en la vista previa..
   • Asegúrese de usar PREVIEW CARD → una vez más para verificar que cualquier cambio sea correcto.
4. Si todo se ve bien, Finalice Tarjeta
   • Si todo se ve bien y la información es correcta después de su última Vista Previa, use el endpoint FINALIZE CARD → para finalizar la nueva tarjeta. Una vez finalizada, ésta puede ser agregada al trabajo de impresión.

Proceso de Checkout

De igual forma que la creación de tarjetas, un trabajo de impresión debe de ser finalizado antes de que sus tarjetas sean enviadas a imprenta. Esto permite que los trabajos sean modificados antes de ser finalizados. También facilita el tener un “carrito de compras” al cual el usuario puede seguir agregando tarjetas.

1. Crear Trabajo de Impresión
   • Use el endpoint CREATE A PRINT JOB → para crear su trabajo de impresión. Las tarjetas pueden ser añadidas durante la creación, durante, o ámbos..
2. Agregue Tarjetas al Trabajo de Impresión
   • Use el endpoint ADD CARDS TO A PRINT JOB → para añadir más tarjetas a un trabajo de impresión ya existente.
3. Select how many copies of each card
   • Use el endpoint UPDATE PRINT JOB → para seleccionar cuántas copias de cada tarjeta quiere en el trabajo de impresión.
   Nota: Cada tarjeta en cierto trabajo de impresión tendrá el mismo número de copias. Si usted necesita un número de copias diferente de alguna tarjeta, cree un trabajo de impresión separado para ésta.
4. Seleccione su proveedor de correo
   • Use el endpoint FETCH SHIPPING PROVIDERS → para veruna lista de los proveedores de correo existentes.
   • UPDATE PRINT JOB → con el ID de su proveedor elegido.
5. Seleccione una Dirección de Entrega
   • Use el endpoint FETCH ALL ADDRESSES → para obtener todas las direcciones  de entrega disponibles.
   • Cree una nueva dirección de entrega si la dirección necesaria no está enlistada, usando el endpoint CREATE SHIPPING ADDRESS →.
   • Si necesita usar una dirección por única ocasión (no quiere guardarla para uso futuro), use el endpoint UPDATE PRINT JOB → para agregar una dirección de único uso al trabajo de impresión.
6. Revisa Balance de Cuenta
   • Use el endpoint CHECK BALANCE → para asegurarse de que tiene suficientes fondos para cubrir el trabajo de impresión, antes de enviarlo.
   • Si la cuenta necesita recarga de fondos, use el endpoint ADD FUNDS →.
7. Enviar el Trabajo de Impresión a  Producción
   • Use el endpoint SUBMIT PRINT JOB → para enviar el trabajo de impresión a la imprenta.
   Nota: Las órdenes enviadas antes de las 4PM EST son impresas y enviadas por correo el mismo día, por lo que es importante verificarque los detallessean correctos antes de enviar.

Login

Endpoint: POST /api/v2/authenticate

Antes de tomar cualquier acción relacionada con el API, usted debe iniciar sesión o aunteticar un usuario. Para hacerlo, ingrese el correo electrónico y contraseña que por lo general usa para acceder al sistema InstantCard (https://online.instantcard.net). Si los datos son correcto, se enviará un token. Si los datos son incorrectos, se arrojará un mensaje 401.

El token es un parámetro requerido para cualquier acción o llamada API subsecuente.

El token expira. Por lo tanto, usted necesita ingresar antes de cada sesión para asegurar que está usando un token válido.

Para realizar pruebas, usted puede usar las siguientes credenciales (sólo le solicitará email y contrasela):

email: [email protected]
contraseña: instantcardapi
ID de organización: 20003827 (InstantCard API)

Acción Muestra:

Respuestas de Éxito de Muestra:

Obtenga perfil de usuario auténtico

Endpoint: GET /api/v2/profile/me

Once you have successfully logged in, you may retrieve your stored user information via this endpoint. This may be used to display the logged-in username, etc.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Card

Endpoint: POST api/v2/organizations/{organization_id}/cards

authorization

card[card_template_id]

card[data]

First you must create the new card based on and existing template. If you do not know the ID for your template, you may retrieve a list of templates using the CARD TEMPLATES ENDPOINT. Additionally, each template will have different variable fields needed for the “data” key value. If you do not know these values, you may retrieve them using the TEMPLATE FIELDS ENDPOINT.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

NOTE: The card created via this endpoint will not be ready for printing. It must first be finalized using the FINALIZE CARD endpoint. This way you may PREVIEW CARD and UPDATE CARD if necessary before finalization.

Sample Call:

Error Status Codes

Sample Successful Response:

Preview Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/preview

authorization

This is used to preview the card you just created (or may be used after the card is finalized). While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint returns two Base64  strings representing both the front and the back card images. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:

Error Status Codes

Sample Successful Response:

Update/Edit Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}

authorization

card[data]

If there is a problem with the card you just created, you may use this endpoint to make changes before finalization. This may also be used to update finalized card items—for example, if you wish to update the expiry for a given card.

While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode an image to Base64 →

Sample Call:

Error Status Codes

Sample Successful Response:

Finalize Card

Endpoint: PATCH api/v2/organizations/{organization_id}/cards/{id}/finalize

authorization

This is used to finalize a card. All cards must be finalized before they may be added to a print job. While the card ID is not added as a header key/value, it is required within the endpoint URL. This Card ID number is the same as that returned in the first entry in the JSON object returned when using the CREATE A CARD endpoint.

Note: If you don’t know the card ID for the card you wish to preview, please use the SEARCH FOR A CARD endpoint.

This endpoint may return Base64 strings where there are images found on the card. For brevity, there is an “*” placed where normally there would be a Base64 string.  Here’s a helpful reference on using JavaScript to decode a Base64 string→

Sample Call:

Error Status Codes

Sample Successful Response:

Search for a Card

Endpoint: GET /api/v2/organizations/20003827/cards/search

authorization

term

page_size

page

This endpoint uses a string to search for a card or cards. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete a Card

Endpoint: DELETE api/v2/organizations/{organization_id}/cards/{id}

authorization

This endpoint deletes a given card.

If you do not know the ID of the card you wish to delete, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Cards

Endpoint: GET api/v2/organizations/{organization_id}/cards

authorization

page_size

page

This endpoint retrieves every card for a given organization. It returns a JSON array of objects. Each object contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

All images return the value “image” to reduce the information returned. To preview images, please use the PREVIEW CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Card

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}

authorization

This enpoint returns a JSON object which contains a card’s ID, template ID, organization ID, its data, and when it was last printed/submitted for printing.

If you do not know the ID of the card you wish to fetch, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Card Print History

Endpoint: GET api/v2/organizations/{organization_id}/cards/{id}/print_history

authorization

This endpoint gives the print history of a given card. It returns a JSON array of objects. Each object represents one print order and includes both the status and the time it was processed. A status of “0” indicates the card has not yet been printed. A status of “1” indicates the card has been printed and sent.

If you do not know the ID of the card whose history you wish to view, use the SEARCH for a CARD endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs

To order cards, you must create a new print job. You may either elect to use an address on file or a “One off” address. One-off address data is not saved and is used only for the given print job. To send to a new address you want saved or to search for an adress ID which already exists, use the ADDRESSES endpoints.

Once created, a print job may be modified via the UPDATE PRINT JOB endpoint, or you may add cards to it via the ADD CARDS endpoint. (This is why the “print_job[card_ids]” parameter is not required when initially creating a print job.) If you do not know the ID of your desired shipping provider, you may retrieve a list of available shipping providers using the SHIPPING PROVIDERS endpoint.

NOTEs:
• Creating a print job will not automatically send cards to be printed. You must use the SUBMIT PRINT JOB endpoint to finalize an order.
• The print_job[card_ids] parameter should be an array of strings—each string being a card ID number. Even if you are ordering a single card, it must be in the form “[264561]”

Sample Call:

Error Status Codes

Sample Successful Response:

Update a Print Job

Endpoint: PATCH api/v2/organizations/{organization_id}/print_jobs/{id}

To update a print job which was already created, use this endpoint.

Note: patching the print job automatically resets the shipping provider id to “null.” Make sure to resend this value with the patch.

Sample Call:

Error Status Codes

Sample Successful Response:

Add Card(s) to a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs/{id}/add_cards

Use this endpoint to add cards to a print job which already exists. If you do not know the print job ID, use the FETCH ALL PRINT JOBS endpoint.

Note: The number of each card printed is inherent to the print job itself. By adding a card to a given job, you will be requesting whatever number of cards is specified within that job. If you need a different amount of a given card, create a new print job.

Sample Call:

Error Status Codes

Sample Successful Response:

Remove a Card from a Print Job

Endpoint: DELETE api/v2/organizations/{organization_id}/print_jobs/{id}/remove_cards/{card_id}

This endpoint will remove an individual card from a print job. To remove multiple cards you must call this endpoint for each card.

Sample Call:

Error Status Codes

Sample Successful Response:

Check Balance to Submit a Print Job

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}/check_balance

Before submitting a print job, you must check the account balance to make sure there are enough funds to cover the given job.

If the balance covers the print job, “true” is returned; if not, “false” is returned.

Sample Call:

Error Status Codes

Sample Successful Response:

Submit a Print Job

Endpoint: POST api/v2/organizations/{organization_id}/print_jobs/{id}/print

Once you are ready to send a print job to be printed, and have verified there are enough funds for the given job, you may use this endpoint to submit a print job.

Note: Print Jobs submitted before 4PM EST are printed and shipped same day. Please make sure to verify all details for a given print job before submitting, as it is likely to be fulfilled right away.

Sample Call:

Error Status Codes

Sample Successful Response:

Print Job Charge Details

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}/charge_details

Use this endpoint to fetch charge detail for an already submitted print job.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Print Job

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}

This endpoint fetches a single print job. You may use thi to check whether a print job is correct before using the SUBMIT PRINT JOB endpoint, or to verify that a given job has been submitted.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Print Jobs

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs

This endpoint fetches all print jobs. You may also specify between created (not submitted) and submitted print jobs using the optional “status” parameter.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Organization Details

Endpoint: GET api/v2/organizations/{id}

This endpoint fetches your organization’s name, total number of cards, and number of card templates.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Organization Balance

Endpoint: GET api/v2/organizations/{id}/balance

This endpoint fetches your organization’s current balance. If the balance is negative (i.e. in overdraft) it is returned in parenthesis.

$5.50—Positive Balance
($5.50)—Negative Balance

If you need to add more funds to your account, please use the ADD FUNDS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Listt of Shipping Providers

Endpoint: GET api/v2/organizations/{id}/shipping_providers

This endpoint fetches all shipping providers available to your organization. The response is an array of JSON objects. Each object represents a shipping provider—giving both an ID number and the provider name. The ID number is what is used when creating a print job.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Print Job

Endpoint: GET api/v2/organizations/{organization_id}/print_jobs/{id}

This endpoint adds the specified “amount” to the organization’s account balance.If the payment is successfully processed, “true” will be returned. If not, you will receive an error message specific to the error (e.g. “error”: “Your card’s expiration year is invalid.”)

For testing purposes, you may use the following credit card details in the staging environment:

Sample Call:

Error Status Codes

Sample Successful Response:

Financial Transactions

Endpoint: GET api/v2/organizations/{id}/financial_transactions

This endpoint fetches every financial transaction for your organization. It returns an array of JSON objects. Each object contains all of the details for an individual transaction.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch Template IDs

Endpoint: GET api/v2/organizations/{organization_id}/card_templates

This endpoint fetches all card templates for your organization by name and ID. It returns an array of JSON objects. Each object contains the template’s ID number and its name.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Template’s Fields

Endpoint: GET api/v2/organizations/{organization_id}/card_templates/{id}/fields

This endpoint fetches all of the variable fields for a given template. Each of these fields is a parameter when using the CREATE A CARD endpoint. Organizations with multiple templates will need to reference the fields for a given template when a new card is being created.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Addresses

Endpoint: GET api/v2/organizations/{organization_id}/addresses

This endpoint fetches all addresses.

Sample Call:

Error Status Codes

Sample Successful Response:

Create an Address

Endpoint: POST api/v2/organizations/{organization_id}/addresses

This endpoint creates a new shipping address. Since addresses were designed to work in tandem with your organization’s contacts, there is the option to associate the address with a contact or to create a contact within this endpoint (you must do one of these things).

(*) Important: You must either include contact name and email or include the ID of a pre-created contact. 

In this example we have created a contact within the create an address endpoint. If you wish to create a contact before defining his or her address, use the CREATE A CONTACT endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Address

Endpoint: GET api/v2/organizations/{organization_id}/addresses/{id}

This endpoint fetches a single address. If you do nt know the ID of the address you wish to find, use the FETCH ALL ADDRESSES endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Update an Address

Endpoint: PATCH api/v2/organizations/{organization_id}/addresses/{id}

This endpoint updates/changes an already existing shipping address.

Warning: If you failed to associate a contact with your address when creating it, this endpoint will return a 501 error.

In this example we change the address state to Colorado.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete an Address

Endpoint: DELETE api/v2/organizations/{organization_id}/addresses/{id}

This endpoint deletes a single address. If you don’t know the ID of the address you wish to delete, use the FETCH ALL ADDRESSES endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch All Contacts

Endpoint: GET api/v2/organizations/{organization_id}/addresses

This endpoint fetches all contacts, along with the addresses associated with them. If you need to associate an address with a contact, use the UPDATE ADDRESS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Create a Contact

Endpoint: POST api/v2/organizations/{organization_id}/contacts

This endpoint creates a new contact. Since contacts were designed to work in tandem with your organization’s addressess, there is the option to associate any address with a contact. You may do this by using the contact ID (once the contact is created) with the UPDATE ADDRESS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response:

Fetch a Single Contact

Endpoint: GET api/v2/organizations/{organization_id}/contacts/{id}

This endpoint fetches a single contact. If you don’t know the ID of the contact you wish to find, use the FETCH ALL CONTACTS endpoint. If there are any addresses associated with the contact, they will be returned in an array with the “addresses” key.

Sample Call:

Error Status Codes

Sample Successful Response:

Update a Contact

Endpoint: PATCH api/v2/organizations/{organization_id}/contacts/{id}

This endpoint updates/edits an already existing contact. Since contacts were designed to work in tandem with your organization’s addresses, there is the option to associate any address with a contact. You may do this by using the contact ID (once the contact is created) with the UPDATE ADDRESS endpoint.

In this example, we update the given contact with an alt email and alt phone number.

Sample Call:

Error Status Codes

Sample Successful Response:

Delete a Contact

Endpoint: DELETE api/v2/organizations/{organization_id}/contacts/{id}

This endpoint deletes a single contact. If you don’t know the ID of the contact you wish to delete, use the FETCH ALL CONTACTS endpoint.

Sample Call:

Error Status Codes

Sample Successful Response: