Query
Il modello per le opportunità di query segue da vicino quello dell'API lead con la restrizione aggiunta che il parametro filterType accetta i campi elencati nell'array searchableFields o della chiamata di descrizione corrispondente, o dedupeFields. Se si utilizzano campi opportunità personalizzati, nella matrice searchableFields verranno elencati solo i campi opportunità personalizzati di tipo String o Integer.
GET /rest/v1/opportunities.json?filterType=marketoGUID&filterValues=dff23271-f996-47d7-984f-f2676861b5fa&dff23271-f996-47d7-984f-f2676861b5fc,dff23271-f996-47d7-984f-f2676861b5fb
{
"requestId":"e42b#14272d07d78",
"success":true,
"result":[
{
"seq":0,
"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fa ",
"externalOpportunityId":"19UYA31581L000000",
"name":"Chairs",
"description":"Chairs",
"amount":"1604.47",
"source":"Inbound Sales Call/Email"
},
{
"seq":1,
"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fc ",
"externalOpportunityId":"29UYA31581L000000",
"name":"Big Dog Day Care-Phase12",
"description":"Big Dog Day Care-Phase12",
"amount":"1604.47",
"source":"Email"
}
]
}
È inoltre possibile includere i parametri di query facoltativi fields, per la restituzione di campi opportunità aggiuntivi, nextPageToken, per il paging attraverso set di dimensioni maggiori del batch, batchSize, che per impostazione predefinita ha un massimo di 300. Quando si richiede un elenco di fields, se un particolare campo è richiesto ma non restituito, il valore è implicitamente nullo.
Crea e aggiorna
Le opportunità seguono da vicino il pattern API dei lead, con alcune limitazioni. I valori disponibili per action sono: createOnly, createOrUpdate e updateOnly. Quando si utilizza la modalità createOnly o createOrUpdate, il campo externalOpportunityId deve essere incluso in ogni record. Per la modalità updateOnly è possibile utilizzare marketoGUID o externalOpportunityId. La modalità predefinita è createOrUpdate se non specificata.
Il parametro lookupField dell'API lead non è disponibile e viene sostituito dal parametro dedupeBy, valido solo se action è updateOnly. I valori disponibili per dedupeBy sono "dedupeFields" o "idField" specificati dalla chiamata di descrizione rispettivamente come externalOpportunityId e marketoGUID. Se dedupeBy non è specificato, per impostazione predefinita viene utilizzata la modalità dedupeFields. Il campo "name" non può essere nullo.
È possibile inviare fino a 300 record alla volta.
POST /rest/v1/opportunities.json
{
"action":"createOrUpdate",
"dedupeBy":"dedupeFields",
"input":[
{
"externalOpportunityId":"19UYA31581L000000",
"name":"Chairs",
"description":"Chairs",
"amount":"1604.47",
"source":"Inbound Sales Call/Email"
},
{
"externalOpportunityId":"29UYA31581L000000",
"name":"Big Dog Day Care-Phase12",
"description":"Big Dog Day Care-Phase12",
"amount":"1604.47",
"source":"Email"
}
]
}
{
"requestId":"e42b#14272d07d78",
"success":true,
"result":[
{
"seq":0,
"status":"updated",
"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb"
},
{
"seq":1,
"status":"created",
"marketoGUID":"cff23271-f996-47d7-984f-f2676861b5fb"
}
]
}
L'API risponderà con marketoGUID per ogni record, nonché con un campo status, che indica l'esito positivo o negativo di ogni record e un campo seq utilizzato per correlare i record inviati, in base all'ordine della risposta. Il numero nel campo è l’indice del record inviato nella richiesta.
Campi
L’oggetto company contiene un set di campi. Ogni definizione di campo è composta da un insieme di attributi che descrivono il campo. Esempi di attributi sono nome visualizzato, nome API e dataType. Questi attributi sono noti collettivamente come metadati.
I seguenti endpoint consentono di eseguire query sui campi dell’oggetto aziendale. Queste API richiedono che l'utente API proprietario abbia un ruolo con una o entrambe le autorizzazioni Read-Write Schema Standard Field o Read-Write Schema Custom Field.
Campi query
La query dei campi dell’opportunità è semplice. Puoi eseguire query in un singolo campo aziendale per nome API o nel set di tutti i campi aziendali.
Per nome
L'endpoint Ottieni campo opportunità per nome recupera i metadati per un singolo campo nell'oggetto aziendale. Il parametro di percorso fieldApiName richiesto specifica il nome API del campo. La risposta è simile all'endpoint Describe Opportunity ma contiene metadati aggiuntivi, ad esempio l'attributo isCustom, che indica se il campo è un campo personalizzato.
GET /rest/v1/opportunities/schema/fields/externalOpportunityId.json
{
"requestId": "12331#17e9779cb4b",
"result": [
{
"displayName": "SFDC Oppty Id",
"name": "externalOpportunityId",
"description": null,
"dataType": "string",
"length": 50,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
}
],
"success": true
}
Sfogliare
L'endpoint Get Opportunity Fields recupera i metadati per tutti i campi nell'oggetto società. Per impostazione predefinita, vengono restituiti al massimo 300 record. È possibile utilizzare il parametro di query batchSize per ridurre questo numero. Se l'attributo moreResult è true, significa che sono disponibili altri risultati. Continua a chiamare questo endpoint fino a quando l’attributo moreResult restituisce false, il che significa che non sono disponibili risultati. I nextPageToken restituiti da questa API devono essere sempre riutilizzati per la successiva iterazione di questa chiamata.
GET /rest/v1/opportunities/schema/fields.json?batchSize=5
{
"requestId": "b4a#17e995b31da",
"result": [
{
"displayName": "SFDC Oppty Id",
"name": "externalOpportunityId",
"description": null,
"dataType": "string",
"length": 50,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Name",
"name": "name",
"description": null,
"dataType": "string",
"length": 255,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Description",
"name": "description",
"description": null,
"dataType": "string",
"length": 2000,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Type",
"name": "type",
"description": null,
"dataType": "string",
"length": 255,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
},
{
"displayName": "Stage",
"name": "stage",
"description": null,
"dataType": "string",
"length": 255,
"isHidden": false,
"isHtmlEncodingInEmail": true,
"isSensitive": false,
"isCustom": false,
"isApiCreated": false
}
],
"success": true,
"nextPageToken": "E5ZONGE4SAHALYYW6FS25KB5BM======",
"moreResult": true
}